kotlin-types-value-class

name	kotlin-types-value-class
description	Use when writing or reviewing Kotlin type declarations to choose @JvmInline value class over data class where appropriate, including Compose stability implications. Technique-layer skill — complements the codebase-specific kotlin-expert.

Kotlin value class vs data class

Core principle

Prefer @JvmInline value class for single-field types that carry domain meaning. Data classes are for aggregating multiple fields. A value class gives you type safety (you can't mix up UserId and String) without the allocation overhead of a data class.

When to use this skill

• Writing a new Kotlin type that wraps a single value
• Reviewing a data class that has only one property
• Seeing primitive types (String, Long, Int, etc.) used where a domain type would prevent misuse
• Compose compiler reports showing unstable parameters that could be value classes

Decision flow

Situation	Prefer
Single field + domain-meaningful (UserId, EmailAddress, Percentage)	@JvmInline value class
Single field + no domain meaning (just grouping)	Type alias or keep the primitive
Multiple fields	Data class
Needs custom equals/hashCode/toString beyond the wrapped value	Data class (value classes delegate to the underlying type)
Used as a generic type argument or nullable in hot paths