Design systems on Android · Series · Part 6 of 6

Shipping an Android design system: publishing, CI, docs and the bugs I hit

A design system that only lives in its author's project is a style guide with extra steps. It becomes a system when other apps can depend on it, when changes are checked automatically, and when the documentation stays true. This final part covers publishing the library, CI, the docs site and the sample as living documentation, then collects the real bugs hit while building the example, because those are the most transferable lessons.

A small, deliberate public API

A library's public surface is a promise. Kotlin can enforce discipline about it: in explicit API mode the compiler refuses a declaration that does not state its visibility, and a public one must state its return type.

kotlin {
    // A design system is public API first: every declaration must state its visibility.
    explicitApi()
    compilerOptions { jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17) }
}

dependencies {
    api(libs.androidx.appcompat)       // consumers see AppCompat types through our views
    implementation(libs.androidx.core.ktx)
}

The choice between api and implementation is itself a design decision. AppCompat is api because the components extend its classes, so consumers need it on their compile classpath. Core KTX is only used inside, so it is implementation and does not leak.

Helpers that components share but consumers should not use (stateColors, roundedRect, rippleOf) are internal. Those that consumers genuinely need (mdsColor, mdsPx) are public and documented.

Publishing the library

An Android library publishes an AAR plus a Gradle module file. The relevant configuration is small:

android {
    publishing {
        singleVariant("release") { withSourcesJar() }
    }
}

afterEvaluate {
    publishing {
        publications {
            register<MavenPublication>("release") {
                from(components["release"])
                groupId = "io.github.liconrepo"
                artifactId = "mds"
                version = project.version.toString()
                pom { name.set("Mobile Design System"); ... }
            }
        }
    }
}

afterEvaluate is needed because the Android Gradle Plugin creates the release component late. Always test the publication on your own machine first, before anything public:

./gradlew :designsystem:publishReleasePublicationToMavenLocal

Then in a throwaway project:

repositories { mavenLocal() }
dependencies { implementation("io.github.liconrepo:mds:0.1.0") }

A real release also needs a version tag. Options, from lightest to heaviest:

The example repo is configured for local publishing and JitPack. It has not been published to a public registry, which is the honest state of the version in this series.

Semantic versioning for a design system

Tokens and XML attribute names are API too. Renaming mdsColorPrimary breaks every consumer theme even though no Kotlin changed. A changelog (CHANGELOG.md in the repo) is part of the contract.

Continuous integration

The workflow is deliberately short, so it stays green and trusted:

- uses: actions/setup-java@v4
  with: { distribution: temurin, java-version: 17 }
- uses: gradle/actions/setup-gradle@v4
- name: Unit tests
  run: ./gradlew :designsystem:testDebugUnitTest
- name: Lint
  run: ./gradlew :designsystem:lintDebug
- name: Build sample
  run: ./gradlew :sample:assembleDebug

Building the sample on every change is the point that is often skipped. It is the cheapest test that a public API change did not break a real consumer.

Two further additions are worth planning but are not in the example yet: screenshot tests, so a pixel-level regression in a component is caught, and a binary-compatibility check, so an accidental public API change fails the build.

Test the logic that is not a view

Views are hard to unit test; pure functions are easy. The avatar's initials and colour-choice logic is pulled into a plain object with its own tests:

@Test fun `two words use first and last initial`() =
    assertEquals("AL", AvatarText.initials("ada king lovelace"))

@Test fun `tone is stable and case-insensitive`() {
    assertSame(AvatarText.tone("Grace Hopper"), AvatarText.tone("  grace hopper "))
}

Docs and sample as part of the product

• Docs as Markdown in the repo. docs/principles.md, tokens.md, theming.md, layers.md, components.md and adding-a-component.md change in the same pull request as the code they describe. The repo also publishes them as a website at liconrepo.github.io/MobileDesignSystem.
• A contributor checklist (adding-a-component.md) turns taste into steps: justify it, name it, use tokens, set background before padding, handle state, keep helpers internal, add it to the sample and the changelog.
• The sample reads tokens live. Its colour, type and spacing tables are generated from the current theme, so they cannot go stale.

Bugs I hit, and what they teach

None of these are exotic. All of them cost time, which is why they are worth listing.

The theme-switch bug and the test that lied

The blank bars showed up only after a theme or brand switch. Cold starts looked perfect. I then spent a while "bisecting" by disabling parts of my insets code, and certain variants appeared to fix it. They did not. Without the top padding, the layout sat higher on screen by the height of the status bar, so my scripted tap on the dark-mode switch landed on empty space. The activity was never recreated, so of course there was no bug. The check was invalid, not the fix.

The lesson is general: before trusting a "works now" result, confirm the test actually did what you think it did. A log line in onCreate proved it in seconds.

What the sample does now:

/**
 * Relaunches as a fresh Activity instead of calling recreate(): on API 35 a recreated edge-to-edge
 * window kept the system bars' insets as padding on the emulator, a fresh launch does not.
 */
private fun restart() {
    startActivity(Intent(this, MainActivity::class.java).addFlags(Intent.FLAG_ACTIVITY_NO_ANIMATION))
    finish()
    @Suppress("DEPRECATION")
    overridePendingTransition(0, 0)
}

The manifest declares android:configChanges="uiMode" so a system dark-mode switch arrives at onConfigurationChanged, which calls restart(). I verified this on an emulator, not on a range of physical devices, and I did not find the framework-level cause, so treat it as a workaround that worked rather than as a diagnosis. Keep your own device matrix in mind.

Adopting this in a real company

1. Start from audit, not from components. List the colours, sizes and button styles in your app. The count is usually surprising and makes the case.
2. Tokens first. Introduce semantic colour roles and migrate screens to them before building a single component.
3. Build the three components you use most. Usually a button, a text field and a card. Ship them, then ask what is missing.
4. Write the principles down and put them where decisions are made: in pull request templates.
5. Make contribution easy. A system owned by one team becomes a bottleneck; the checklist and sample make contributions reviewable.
6. Measure adoption. Count remaining hard-coded colours and one-off button styles, and watch the number fall.
7. Mind your boundaries. If you build one while employed, keep your employer's code, assets and internal knowledge out of public work, and check your contract before publishing.

What this series left out

To keep the example small, it does not cover: Compose (by design), right-to-left layout testing, large-screen and foldable layouts, localisation beyond string resources, a Figma token pipeline, or automated screenshot tests. Each is a good next contribution, and the repo's issue tracker is the place to propose them.

Try it yourself

1. Publish to mavenLocal() and consume the library from a brand-new Android project. Apply Theme.Mds and use one button.
2. Break something on purpose, such as removing an explicitApi modifier or a test, and watch CI catch it on a pull request.
3. Pick one item from "what this series left out", implement it, and open a pull request against the repo.