N05 — Modify SystemUI

SystemUI is the best first platform change because you can see the result. There is no instrumentation and no log to interpret: either the status bar looks different or it does not. It is also a useful corrective to the idea that system apps are magic — SystemUI is an Android app with a manifest, a resource directory and a build module, installed on the system image, and it sits in the system layer of the platform stack rather than in the framework.¹

Hardware note: this needs a platform build and a boot, and the build follows the AOSP build documentation.²

TL;DR#

SystemUI is an app in frameworks/base/packages/SystemUI/, built as the SystemUI module.
Two ways in: change the source, or overlay resources without touching the source.
An RRO changes resources at runtime, which is faster to iterate and easier to undo.
Resources and code both live under the module, with res/ and src/ side by side.
A reboot (or a SystemUI restart) is how you see the change.

What you are building#

One visible change, chosen from a menu:

A resource overlay that changes a dimension or a colour used by the status bar.
A source change to a status bar layout, rebuilt into the image.
A quick settings tile, which is a small feature rather than a style change.

Pick one. Doing all three in one sitting produces a build you cannot debug.

Choosing your route#

Route	Effort per iteration	Risk	Good for
RRO overlay	Push and restart, no full build	Low, reversible	Colours, dimensions, strings
Source edit in SystemUI	Rebuild the module and the image	Medium	Layout and behaviour
New quick settings tile	Module plus registration	Medium	Learning how SystemUI composes features

The overlay route is not a toy. Runtime resource overlays are how a device customises the platform without forking it, and the mechanism is the same one an OEM uses.³

Steps#

Route A: an RRO#

Find the resource you want to change
Look in frameworks/base/packages/SystemUI/res/ for the value you want. Resource names are stable across a release; the file they live in is less so, because resources get reorganised.
You should seeA named resource in SystemUI's res directory.
Build an overlay APK
An RRO is an APK with no code, a manifest that declares the target package, and the resource values you want to override. The AOSP runtime resource overlay documentation describes the manifest attributes and the package naming rules; follow it rather than inventing an overlay element from memory.³
You should seeAn APK with an overlay target package.
Install and enable it
```
adb install -r overlay.apk
adb shell cmd overlay list
adb shell cmd overlay enable <package>/<overlay>
```
cmd overlay list shows enabled and disabled overlays and the target package for each. Enabling one applies it immediately to the running app.
You should seeThe overlay is listed and enabled.
Restart SystemUI
Some resources are read at process start. If the overlay applies but nothing changes, restart the SystemUI process — the simplest reliable way on a userdebug build is a reboot. On a device you control, killing the process causes it to be restarted by the system.
You should seeThe change appears without a full reboot.

Route B: a source change#

Find the layout or the code
The module is SystemUI in packages/SystemUI/Android.bp, with broad source globs over src/. Status bar code lives under src/com/android/systemui/statusbar/, quick settings under src/com/android/systemui/qs/, and resources under res/. Those directory names are stable; the individual files inside them change often, so search rather than guess.
You should seeA file under packages/SystemUI you can edit.
Make the smallest possible change
Change one dimension, one visibility or one string. A large refactor of SystemUI is not a beginner platform change — it is a project with its own test surface.
You should seeA diff you can explain in one sentence.
Build the module
```
source build/envsetup.sh
lunch <your target from N01>
m SystemUI
```
Building the module alone is much faster than m and catches compile errors before you spend time assembling an image.
You should seeThe module compiles on its own before the image does.
Rebuild the image and boot
Build the target as in N01, flash or launch it, and look at the result.
You should seeThe device boots with your change.

Build and check#

Iterate on SystemUI

$ source build/envsetup.sh
lunch <your target from N01>
m SystemUI
adb shell cmd overlay list
adb logcat -s SystemUI

Example output

Illustrative — no build was executed in this run.

<your target from N01> is a placeholder deliberately. The exact lunch target should be copied from the AOSP build page for your branch.

The files you touched#

The paths below are readable on Android Code Search even without a local checkout, which is useful when you want to confirm a file still exists before editing it.

⁴

Android.bpthe SystemUI android_app module and its source globs
status bar code
quick settings code
the resources an overlay would target

Verification#

An overlay change is verified by the visible result plus cmd overlay list showing it enabled. A source change is verified by the build succeeding and the image showing it. If SystemUI crashes on boot, adb logcat -s SystemUI AndroidRuntime shows the stack; a crash loop in SystemUI looks like a device with no status bar and a black wallpaper.

What can go wrong#

The overlay targets the wrong package. It installs, enables, and changes nothing, because the target package string does not match SystemUI's.
The resource is not overlaid because it is not declared. RRO can only replace resources that exist and are declared overlaid. A private or hard-coded value cannot be reached this way.
SystemUI crash-loops. A layout or resource change can throw during inflation. Read logcat, fix or revert; the rest of the system usually boots fine without SystemUI, which is why this is survivable.
The change does not appear after a build. The image you booted is not the one you built, or the module is installed from a prebuilt rather than from source.
A feature flag gates the code. Much of modern SystemUI is behind aconfig flags; a change to a flagged code path may be invisible until the flag is on.⁵
m SystemUI succeeds but the image does not change. Building a module does not reassemble the image; you still need the image build and a boot.