| name | jetpack-best-practices |
| description | USE THIS when writing or reviewing Jetpack Compose / Kotlin code in packages/cds-android or apps/android-app - @Composable APIs, Modifier parameters, CompositionLocal, state hoisting, or naming. Not for React or React Native work. |
Jetpack Compose API guidelines
references/compose-api-guidelines.md is the official AOSP Compose API guidelines document,
vendored verbatim. Read it before writing or reviewing a Compose API. It is the authority here;
do not invent house style that contradicts it, and do not paraphrase it from memory.
How the requirement levels apply to us
The document assigns different requirement levels to different audiences. CDS Android is
"Library development based on Jetpack Compose" — we publish @Composable functions and
supporting types for other teams to consume. Read the MUST/SHOULD/MAY markers for that audience,
not the app-development ones. In practice we hold close to the framework-development bar, because
anything we ship publicly is expensive to change later.
The rules that come up most in this codebase
These are the ones worth checking on every change. The document explains each in full.
- Every element accepts and respects a
Modifier parameter. It is the first optional
parameter, defaults to Modifier, is applied to the outermost layout node the element emits, and
is used exactly once. Never accept a Modifier and drop it.
- Composables that emit UI return
Unit and are named as PascalCase nouns (Button,
SlideButton) — they declare a piece of UI rather than performing an action.
- Hoist state. Prefer stateless composables taking a value plus an
onValueChange callback
over ones that own their state internally.
CompositionLocal is for cross-cutting context, not for passing parameters. In this
codebase that means theme. A local should have a sensible default and should not be how a caller
configures a specific component.- Parameter order: required parameters, then
modifier, then other optional parameters, then a
trailing @Composable content lambda if there is one.
- Default values belong in the signature, so callers can see them and override any one of them
independently.
Boundary rules specific to CDS Android
Complementary to the guidelines, not covered by them. packages/cds-android/AGENTS.md is the full
version:
:cds compiles with Kotlin explicit API mode. Every public declaration is a customer promise —
make it a decision, not a compiler-satisfying reflex, and default to internal.- Read tokens through
CdsTheme.colors / CdsTheme.space; author themes with cdsTheme { }.
LocalCdsTheme is public only so custom Modifier nodes can read theme outside composition.
- Never widen a declaration's visibility just to make
apps/android-app compile.
Related reading
The separate component API guidelines
go deeper on designing individual components (slots, state holders, styling). Not vendored here;
consult it when designing a new component from scratch.
