How google/automotive-design-compose works
1. This is a mixed Kotlin/Android + Rust monorepo
The repository is centered on the DesignCompose SDK for Android Automotive. The Android side is a Gradle multi-project build; the native/live-update path is implemented in Rust crates and bridged into Android through JNI. Several sample apps, test apps, and Figma support tools are included in the same repo.
2. Primary product boundary: the designcompose Android library
designcompose/ is the main runtime library that app developers consume. It contains the Compose renderer, design-doc loading, live update handling, theming/customization, interaction state, layout management, and rendering helpers. It also includes bundled .dcf assets used by tests and demos, such as the Design Switcher document.
3. Document flow starts from Figma and ends in Compose rendering
The core architecture is: Figma document → Rust importer/download/serialization → .dcf serialized document → Android runtime parses/loads it → Compose UI renders it. The runtime can also fetch updates live, so document state is not only static assets but may be refreshed from Figma over the network.
4. Rust crates handle document import, bundle format, layout, and native interop
The native side is split into focused crates:
- dc_figma_import fetches Figma files/resources and converts them into the internal serialized form.
- dc_bundle defines the serialized document/bundle format and includes inspection tooling.
- dc_layout computes layout and converts document layout into the engine’s layout model.
- dc_jni exposes the Rust functionality to Android through JNI.
- dc_squoosh_animation supports animation-related processing.
These crates are the boundary between Figma data and the Android runtime.
5. common/, annotation/, and codegen/ define the developer-facing API surface
- common/ holds shared data types and serialization-friendly model objects used across modules.
- annotation/ defines annotations like design-document/component markers.
- codegen/ is a KSP-based Kotlin compiler plugin that generates stubs and wiring for annotated Composables.
This is the API/compile-time layer that turns app code into DesignCompose-aware entry points.
6. Gradle plugins orchestrate native builds, publishing, and configuration
The plugins/ directory contains custom Gradle plugins, including a Cargo plugin that builds Rust artifacts for Android/host targets and a plugin for setting Figma tokens. build-logic/ contains convention plugins shared across the repo. These pieces are important because the build is not pure Android; Gradle coordinates Kotlin, JNI, and Cargo outputs.
7. Live update is a distinct runtime subsystem
Inside designcompose/, live update support includes token handling, document server settings, and a WebSocket update client. There is also a tools/ws-relay Python service, suggesting a local relay path for websocket-based update traffic. This makes live update a separate networked subsystem, not just a file-loading feature.
8. Design-switching and customization are first-class app concerns
The runtime includes DesignSwitcher, customization contexts, variable management, interaction state, and theme/material mapping. These pieces let an app swap between design docs and override behavior without rebuilding the app. In the architecture diagram, this is the “dynamic configuration” layer sitting between the app and the document renderer.
9. Sample apps demonstrate different integration modes
reference-apps/ contains standalone example apps:
- tutorial shows the end-user onboarding/tutorial flow.
- helloworld is the minimal app example.
- aaos-unbundled/mediacompose demonstrates an Android Automotive media-centric integration.
- cluster-demo is another sample/test app.
These are not just demos; they show how the SDK is consumed in real app shells, with their own assets, manifests, fonts, and activities.
10. integration-tests/ is the validation and benchmark boundary
This folder contains:
- validation/ for visually verifying rendering and behavior against many serialized Figma documents.
- benchmarks/ for startup/performance measurement, including the battleship benchmark app.
- app-common/ for shared test app utilities and fonts.
The presence of many .dcf test assets indicates that serialized document fixtures are a major testing input.
11. Figma-side tooling is split into plugins/widgets
support-figma/ contains the Figma ecosystem tooling:
- extended-layout-plugin for authoring/validation of extended layout and customization metadata.
- auto-content-preview-widget for designer-facing content previews.
- dc_squoosh_designer for animation/timeline authoring.
These tools produce or consume data that ultimately feeds the serialized document flow used by the Android runtime.
12. Docs, scripts, and CI are part of the operational architecture
docs/ hosts the generated documentation site and architecture docs. dev-scripts/ automate formatting, testing, asset updates, and release prep. .github/workflows/ and related files define CI, release, screenshot comparison, code quality, and publishing pipelines. These aren’t runtime components, but they govern how the multi-language system is built, validated, and released.
13. Key external boundaries to show in a diagram
The important external systems are:
- Figma API / Figma Desktop app
- Android apps / Compose runtime
- GitHub Releases and CI
- Rust toolchain and Android NDK for native builds
These boundaries materially affect how data and artifacts move through the system.
14. The simplest accurate architecture diagram
A good high-level diagram would show:
- Figma docs/resources on one side
- Rust import/serialization/layout/JNI in the middle
- Android DesignCompose runtime and generated Kotlin APIs on the other
- Sample/reference apps and test apps consuming the runtime
- Supporting Figma plugins/widgets and CI/build tooling as side systems
The main data artifact flowing through the system is the serialized .dcf document, with live-update traffic as an additional runtime channel.
Main entry points: designcompose Runtime SDK · dc_bundle Bundle Format · dc_jni JNI Bridge · dc_figma_import Figma Import
Components 23
External Systems
Outside services and runtimes the repo integrates with
- Figma · Source of design documents, resources, and live-update data
- Compose · Android UI runtime that DesignCompose renders into
- CI / Releases · GitHub-based validation, publishing, and release automation
Android SDK
Public runtime, API surface, and generated Kotlin entry points
- Runtime SDK · Main DesignCompose library consumed by app developers
designcompose - API Surface · Common data types, annotations, and generated stubs used by apps
common - Renderer · Document loading, layout coordination, and Compose rendering path
designcompose/src/main/java/com/android/designcompose - Live Update · WebSocket client, server settings, and update handling
designcompose/src/main/java/com/android/designcompose/WebSocketUpdateClient.kt - Dynamic Config · Design switching, customization, variables, interactions, and theme mapping
designcompose/src/main/java/com/android/designcompose/DesignSwitcher.kt - Codegen · Annotation processor that generates DesignCompose wiring
codegen - Annotations · Developer-facing annotations for design-aware components
annotation
Native Rust
Document import, bundle, layout, and JNI bridge layer
- Figma Import · Fetches Figma files/resources and converts them into serialized document form
crates/dc_figma_import - Bundle Format · Serialized document and bundle definition, including inspection tooling
crates/dc_bundle - Layout Engine · Computes and converts document layout into the engine model
crates/dc_layout - JNI Bridge · Exposes Rust functionality to Android through JNI
crates/dc_jni - Animation Proc · Animation-related processing support for native document flow
crates/dc_squoosh_animation
Apps & Tests
Reference apps and validation harnesses consuming the SDK
- Reference Apps · Standalone example apps demonstrating SDK integration modes
reference-apps - Validation Suite · Rendering validation, benchmarks, and shared test app infrastructure
integration-tests - SDK Tests · Runtime tests and fixtures for the main SDK module
designcompose/src/androidTest
Figma Tools
Designer-facing plugins and widgets that produce or inspect design data
- Figma Support · Designer-side tooling that emits or consumes design data and timelines
support-figma
Build & Ops
Gradle, Cargo, scripts, docs, and CI orchestration
- Cargo Plugin · Builds Rust artifacts for Android and host targets
plugins/cargo-plugin - Gradle Plugins · Custom Gradle plugins and configuration helpers
plugins/gradle-plugin - Build Logic · Shared Gradle convention plugins across the repo
build-logic - Docs & Scripts · Documentation, developer scripts, and release automation support
docs
Connections 27
- Figma → Figma Import: design docs · Figma files and resources are imported into serialized form
- Figma Import → Bundle Format: serialize · Importer emits the repository's serialized .dcf document format
- Bundle Format → Runtime SDK: load .dcf · Android runtime loads serialized bundles and fixtures
- Bundle Format → Validation Suite: fixtures · Validation and benchmark suites consume many .dcf test assets
- Bundle Format → Reference Apps: sample assets · Reference apps ship bundled design documents for demos
- Layout Engine → Runtime SDK: layout model · Native layout results are consumed by the Android renderer
- JNI Bridge → Runtime SDK: native bridge · JNI exposes Rust capabilities to the Kotlin runtime
- Figma Import → JNI Bridge: interop · Importer functionality is surfaced through the JNI boundary
- Layout Engine → JNI Bridge: interop · Layout computation is surfaced through the JNI boundary
- Animation Proc → Bundle Format: animation data · Animation processing contributes to serialized document handling
- Annotations → Codegen: annotate · Annotations are the input to generated component wiring
- Codegen → API Surface: generate stubs · KSP generates runtime-facing Kotlin entry points and helpers
- API Surface → Runtime SDK: consume · Apps and generated code compile against the shared API layer
- Runtime SDK → Renderer: render · Main runtime coordinates document parsing, layout, and Compose rendering
- Renderer → Compose: compose UI · Rendered document state is shown inside the host Compose runtime
- Dynamic Config → Renderer: customize · Switching, variables, interactions, and themes modify rendering behavior
- Live Update → Runtime SDK: refresh · Live update changes document state over the network
- Figma → Live Update: websocket / fetch · Runtime can pull remote updates and document content from Figma-related services
- Figma Support → Figma: authoring tools · Plugins and widgets produce or inspect data that feeds the document pipeline
- Reference Apps → Runtime SDK: embed SDK · Samples show how app shells consume the runtime library
- Validation Suite → Runtime SDK: verify SDK · Validation and benchmark apps exercise runtime behavior
- SDK Tests → Runtime SDK: test runtime · SDK-specific tests validate live update, JNI, and rendering behavior
- Cargo Plugin → JNI Bridge: build native · Gradle plugin coordinates Rust builds for Android and host targets
- Gradle Plugins → Cargo Plugin: configure · Higher-level Gradle plugins wrap and configure native build tasks
- Build Logic → Gradle Plugins: shared conventions · Convention plugins are reused across modules and examples
- Docs & Scripts → CI / Releases: automation · Docs, scripts, and workflows support CI, release, and validation flows
- Docs & Scripts → Reference Apps: asset updates · Developer scripts regenerate bundled docs and sample assets