When to Use This Skill
Use this skill when you need to:
- Build a Kotlin Multiplatform library on a non-standard runtime (a custom native renderer, a custom transport, a custom storage engine) and want its Kotlin API to feel like a well-known reference API (Jetpack Compose, SwiftUI, Retrofit, Room, ...) without literally depending on or reimplementing that library's internals
- Design a chainable configuration object (a
Modifier-equivalent) for a custom rendering or layout engine - Design a slot-lambda DSL (
content: Scope.() -> Unit) for a custom scene-graph builder - Decide how far to take the mimicry — plain-function DSL vs. writing an actual Kotlin compiler plugin — before committing engineering time to either
- Document, for future maintainers and for legal clarity, exactly which parts of a reference API were mimicked and which were deliberately changed
Do NOT use this skill when:
- The project already depends on the real reference library (Compose Multiplatform,
Ktor, etc.) and just needs to use it — that is ordinary consumption, not mimicry;
see
kotlin-multiplatform-design-systemfor building a design system on top of real Compose Multiplatform - The goal is a real Kotlin compiler plugin providing true fine-grained recomposition — that is a distinct, much larger undertaking this skill deliberately does not cover; it only tells you when that investment is actually justified (see Decision Table below)
- The goal is copying the reference library's actual source code under a new package — never do this; see Guidelines
Trigger keywords: mimic api, api mimicry, clone api shape, inspired by jetpack compose, custom dsl engine, from-scratch renderer, vulkan ui, metal ui, port api ergonomics, reimplement compose-like dsl, non-compose renderer, engine-agnostic dsl, own compiler-free dsl, api shape porting.
Freshness rule: the reference API you are mimicking changes between its own
releases (Jetpack Compose's Modifier and CompositionLocal surface, SwiftUI's
ViewBuilder, etc.) — re-read the reference API's current public docs before
mimicking a new version's shape. Never mimic from memory or from an old cached
understanding of the reference API; verify against its real current source or docs.
Recommendation First
Default to this approach:
- Catalog the reference API's real public surface first — read its actual current docs/source, don't guess. List the specific types/functions/annotations you intend to mimic.
- Mimic ergonomics, not internals. A chainable
Modifier-style object and a slot-lambda DSL are cheap to mimic faithfully with plain Kotlin. Recomposition, snapshot state, and skipping are not — they depend on the reference's own compiler plugin. Default to a plain-function DSL with explicit invalidation, not a fake compiler plugin. - Never reuse the reference library's package namespace or literal branding. Own
group id, own package, own annotation name (
@EngineUiDsl, not@Composable). - Write a mirror map (
MIRROR_MAP.md) documenting each mimicked primitive, its inspiration, and the deliberate deviation — before writing the second mimicked primitive, not after the tenth.
Why:
- most of a reference API's ergonomics (chainable config, slot lambdas, scoped builders) come from ordinary Kotlin language features, not compiler magic — you get 90% of the developer-experience win for a fraction of the effort
- a real compiler plugin is a permanent maintenance burden riding on your own fork of Kotlin compiler internals — only justified when fine-grained recomposition is a measured, not assumed, performance requirement
- consumers who see
@Composable-shaped code assume@Composable-shaped guarantees; an undocumented gap between mimicked ergonomics and real behavior is where the bug reports come from
// Own annotation, own package — not androidx.compose.runtime.Composable
@DslMarker
annotation class EngineUiDsl
@EngineUiDsl
sealed interface EngineModifier {
fun then(other: EngineModifier): EngineModifier =
if (other is EngineModifier.None) this else CombinedEngineModifier(this, other)
object None : EngineModifier
}
Core Pattern: Mapping Reference Primitives to Plain Kotlin
This method applies to any reference API — the table below uses Jetpack Compose as the running example because it has the richest primitive set (DSL, chain object, scoped ambient values, state), not because this skill is Compose-specific. See "Other reference APIs, same method" below for non-UI examples.
| Reference primitive (e.g. Jetpack Compose) | What actually powers it | Mimicable without a compiler plugin? | Kotlin equivalent |
|---|---|---|---|
@Composable function |
Compose compiler plugin (call-site tracking, skipping) | No — mimicking the annotation without the plugin gives you a plain function call, not real skipping | Own marker annotation (@EngineUiDsl) used as documentation only; be explicit it's not enforced |
Modifier chain |
Plain immutable linked-list-style object with then() |
Yes, fully | Sealed interface + then(), exactly Compose's own shape — no magic involved |
Slot lambda (content: @Composable () -> Unit) |
Trailing lambda + receiver scope, a plain language feature | Yes, fully | fun Box(content: EngineScope.() -> Unit) |
CompositionLocal |
Compose runtime's ambient value propagation through the composition tree | No — depends on the runtime tracking a composition tree | Explicit scope object threaded as a parameter, or a plain ThreadLocal/context object if the design tolerates it |
remember { } / mutableStateOf |
Compose's snapshot state system + recomposition scheduler | No — reimplementing snapshot state from scratch is a multi-month undertaking | An explicit state holder bound to your own render loop's invalidation call (requestRedraw()); callers manage identity/keys themselves |
LaunchedEffect / lifecycle-scoped coroutines |
Compose runtime lifecycle integration | Partially | Your own scene-graph node lifecycle + CoroutineScope bound to node attach/detach |
Decision Table: plain-function DSL vs. real compiler plugin
| Signal | Choose |
|---|---|
| Ergonomics (chainable modifiers, slot DSL, readable call sites) is the goal | Plain-function DSL — covers this fully |
| Fine-grained recomposition/skipping is a measured perf requirement, not assumed | Real compiler plugin — but treat this as its own multi-month project, not an extension of this skill |
| Team size / maintenance budget for owning Kotlin compiler plugin internals long-term | If small, plain-function DSL — a compiler plugin tracks Kotlin compiler versions forever |
Consumers must be able to write literal @Composable functions and get real Compose semantics |
Neither — depend on real Compose Multiplatform instead; mimicry no longer applies |
Other reference APIs, same method
Jetpack Compose is one example, not the scope of this skill. The same catalog → map → decide → mirror-map method applies to any reference API's ergonomics:
| Reference API mimicked | What's mimicked (ergonomics, not internals) | What's explicitly not mimicked |
|---|---|---|
| Retrofit-style declarative service interfaces | interface-with-annotated-methods DSL, generating a typed client at your call boundary |
Retrofit's actual annotation processor / CallAdapter machinery — write a plain factory function instead |
| Room-style DAO annotations | @Dao-shaped method-per-query interface as the ergonomic surface |
Room's KSP-generated implementation — back it with your own hand-written or codegen'd implementation for your storage engine |
SwiftUI's ViewBuilder/declarative tree |
Trailing-closure-equivalent slot lambdas, same as the Compose row above | SwiftUI's own diffing/identity system |
| Jetpack Compose (worked example below) | Modifier chain, slot lambdas, DSL marker annotations |
Snapshot state, recomposition, CompositionLocal propagation |
Worked example: Vulkan-backed UI DSL inspired by Jetpack Compose
One concrete instance of the method above — not the only valid target for this skill.
A KMM library wraps a custom Vulkan rendering backend (via expect/actual +
JNI/cinterop — see kotlin-multiplatform-jni-pro and
kotlin-multiplatform-expect-actual) and needs a Compose-shaped declarative UI layer on
top of it.
Naming below uses a generic Engine placeholder — pick your own project's actual
prefix instead. Do not literally fuse your backend's brand name with the reference
API's own type name (e.g. do not name it VulkanModifier just because the backend is
Vulkan and the mimicked type is Compose's Modifier) unless that fusion is genuinely
your project's established naming convention — it usually isn't, and reads as if it
were copied from a real, verified source when it's just this example's placeholder.
// :library/src/commonMain/kotlin/.../EngineModifier.kt
@EngineUiDsl
sealed interface EngineModifier {
object None : EngineModifier
}
private data class CombinedEngineModifier(
val outer: EngineModifier,
val inner: EngineModifier,
) : EngineModifier
fun EngineModifier.padding(all: Dp): EngineModifier = this.then(PaddingModifier(all))
fun EngineModifier.size(width: Dp, height: Dp): EngineModifier = this.then(SizeModifier(width, height))
// :library/src/commonMain/kotlin/.../EngineScope.kt
class EngineScope internal constructor(private val node: SceneNode) {
@EngineUiDsl
fun Box(modifier: EngineModifier = EngineModifier.None, content: EngineScope.() -> Unit) {
val child = node.addChild(SceneNode.Kind.Box, modifier)
EngineScope(child).content()
}
@EngineUiDsl
fun Text(text: String, modifier: EngineModifier = EngineModifier.None) {
node.addChild(SceneNode.Kind.Text(text), modifier)
}
}
// Entry point — mirrors setContent { } shape, explicit invalidation instead of
// Compose's snapshot-driven recomposition
fun EngineCanvas.setContent(content: EngineScope.() -> Unit) {
val root = SceneNode.root()
EngineScope(root).content()
this.submit(root) // hands the built scene graph to the Vulkan backend
}
This gives callers Compose-shaped call sites (Box(modifier = ...) { Text("Hi") })
without claiming or requiring real Compose compiler behavior. State changes are the
caller's responsibility — call setContent again (or a narrower invalidate()) to
rebuild the affected subtree.
Guidelines
- Never copy the reference library's actual source code under a renamed package — copyright and drift risk; re-derive the shape from its public docs instead
- Never use the reference library's real package prefix (
androidx.compose.*,com.squareup.retrofit2.*) or trademarked product name in your own artifact — own group id, own package, own name - Never apply the reference library's real annotation (
@Composable) to functions your own compiler doesn't process — undefined/misleading behavior for any tooling that expects the real Compose compiler plugin - State plainly in the library's README that it is "API-shape-inspired by X, not compiler-compatible with X, no interop with real X code" — this is the single highest-value sentence for avoiding wrong-expectation bug reports
- Keep a
MIRROR_MAP.mdat the library root: one row per mimicked primitive, its reference inspiration, and the deliberate deviation - This is almost always a library project (see
kotlin-multiplatform-library-publishing), not an app — scaffold accordingly
Testing
class EngineModifierTest {
@Test
fun `then chains in call order`() {
val modifier = EngineModifier.None.padding(8.dp).size(100.dp, 100.dp)
val flattened = modifier.flatten() // test helper walking the CombinedEngineModifier chain
assertEquals(listOf("padding", "size"), flattened.map { it.name })
}
}
class EngineScopeTest {
@Test
fun `Box adds a child scene node with its modifier`() {
val root = SceneNode.root()
EngineScope(root).apply {
Box(modifier = EngineModifier.None.padding(4.dp)) {
Text("hello")
}
}
assertEquals(1, root.children.size)
assertEquals(SceneNode.Kind.Box, root.children.single().kind)
assertEquals(1, root.children.single().children.size)
}
@Test
fun `setContent rebuilds the scene graph on each call`() {
val canvas = FakeEngineCanvas()
var label = "first"
canvas.setContent { Text(label) }
val firstSubmit = canvas.lastSubmittedRoot
label = "second"
canvas.setContent { Text(label) }
assertNotSame(firstSubmit, canvas.lastSubmittedRoot) // explicit rebuild, not diffed
}
}
Common Anti-Patterns
- Copy-pasting real Compose (or any reference library) source under a new package — license and drift risk; the copied code silently diverges from real semantics as the original library evolves. Re-derive the shape from public docs instead.
- Claiming
@Composable-compatible without a real compiler plugin — misleads consumers about recomposition/skipping guarantees they do not actually get; document the gap explicitly instead of implying parity. - Reimplementing Compose's full snapshot-state system "just in case" — a
multi-month undertaking almost never justified by the actual requirement; an explicit
requestRedraw()/rebuild model covers most custom-renderer needs. - Using the reference library's real annotation on non-reference functions —
applying
@Composableto a function your own tooling processes is undefined behavior for any real Compose tooling that later touches the same codebase. - Skipping the
MIRROR_MAP.md— without it, consumers and future maintainers assume full behavioral parity with the reference API and file bugs against the wrong mental model; write it before the second mimicked primitive. - Reusing the reference library's package namespace (
androidx.compose.*) to "borrow" IDE tooling or autocomplete — breaks real Compose compiler expectations if the real library is ever added to the same classpath, and is a trademark/namespace collision risk on publish.
Related Skills
kotlin-multiplatform-library-publishing— this is almost always a library project; publish it the same way as any other KMP librarykotlin-multiplatform-jni-pro— if the custom runtime is native (Vulkan, Metal via cinterop, etc.), the JNI/cinterop bridge for it lives herekotlin-multiplatform-expect-actual— platform-specific backend wiring for the custom rendererkotlin-multiplatform-design-system— use this instead when the target runtime is real Compose Multiplatform; that skill builds a design system on top of the real thing rather than mimicking its shapekotlin-multiplatform-compose-slot-api— slot-lambda patterns for real Compose Multiplatform projects; this skill's slot-lambda guidance is the non-Compose analogkotlin-multiplatform-clean-architecture— layer boundaries still apply inside the library even though there's no:ui/:presentersplit in the app sense
Output Style
When asked about mimicking a reference API's shape, respond in this order:
- recommendation (plain-function DSL, not a compiler plugin, unless justified)
- the specific reference primitives being mapped, and their Kotlin equivalents
- code snippet (one chainable-modifier example + one slot-lambda example)
- what real behavior is explicitly NOT being mimicked (recomposition, skipping, etc.)
- main alternative (a real compiler plugin, or just depending on the real reference library)
Keep the snippet to one modifier chain and one slot function. Always name the specific reference API being mimicked when the user names one — do not speak generically about "a reference API" once a real one (Jetpack Compose, SwiftUI, ...) is named.
Changelog
| Date | Change |
|---|---|
| 2026-07-31 | Initial release. |