reis-mobile 0.3.6 → 0.4.0

package/skills/android-styles/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: android-styles
+description: Use this skill to integrate the Jetpack Compose Styles API into an Android
+  project. This skill guides you through upgrading dependencies, setting up component
+  themes, making custom components styleable, and migrating existing layout properties
+  to use unified styles. Migrate custom design system components, replace hard coded
+  parameters with Style attributes, and use Modifier.styleable for interaction states.
+license: Apache-2.0
+source: https://github.com/android/skills
+routing: manual
+stacks: [android]
+metadata:
+  author: Google LLC
+  last-updated: '2026-09-08'
+  keywords:
+  - Jetpack Compose
+  - Styles
+  - Theming with Styles
+  - Migrate to Styles
+  - Modifier.styleable
+---
+
+## Limitations
+
+- Warn the user that this skill is EXPERIMENTAL and requires updating to alpha version of Compose and opting in to the Experimental APIs.
+- This skill only supports custom UI components and custom themes.
+- This skill does not support Material Design component Styles.
+
+## Prerequisites
+
+### 1. Upgrade dependencies
+
+- The project must use `compileSdk` version 37 or higher.
+- The project must use `androidx.compose.foundation:foundation` version `1.12.0-alpha01` or higher.
+- Alternatively, the project must use Compose BOM version `2026.04.01` or higher.
+- The API requires this exact package: `import
+  androidx.compose.foundation.style.Style`
+
+### 2. Configure compiler options to enable experimental API
+
+You must opt-in to the experimental API at the project level. Add the following
+block to your module's `build.gradle.kts`:
+
+    kotlin {
+        compilerOptions {
+            jvmTarget = JvmTarget.fromTarget("17")
+            freeCompilerArgs.add("-opt-in=androidx.compose.foundation.style.ExperimentalFoundationStyleApi")
+        }
+    }
+
+## Core workflows and guides
+
+Refer to the official documentation to complete specific development tasks:
+
+- Basic Style Usage: To set backgrounds, sizes, and alignments on a component, follow the [Compose Styles Fundamentals
+  Guide](references/android/develop/ui/compose/styles/fundamentals.md).
+- State and Transitions: To configure property changes for state shifts (like pressed or hovered), follow the [Animations and State-Based Styling
+  Guide](references/android/develop/ui/compose/styles/state-animations.md).
+- Architecture Trade offs: To decide when to use a Style versus a standard Modifier, follow the [Styles versus Modifiers
+  Comparison](references/android/develop/ui/compose/styles/styles-vs-modifiers.md).
+- Theme Level Integration: To connect style definitions with custom themes, follow [Theming with Styles](references/android/develop/ui/compose/styles/theming.md) and [Custom Themes in Compose](references/android/develop/ui/compose/designsystems/custom.md).
+
+## Step-by-Step Migration Workflow
+
+### Step 1: Analyze theme structure
+
+1. Locate your central theme file (such as `Theme.kt`).
+2. Identify design tokens. Note references for colors, typography, and shapes (for example, `LocalColorScheme`, `LocalTypography`, or `LocalShapes`).
+3. If the project lacks Jetpack Compose dependencies, stop. Instruct the user to migrate to Jetpack Compose first.
+4. If the project imports `androidx.compose.material.MaterialTheme`, recommend migrating to Material 3 before proceeding.
+
+### Step 2: Establish `ComponentStyles`
+
+1. Create a new file named `ComponentStyles.kt` in your theme directory.
+2. Define a top-level data class to hold your component styles, for example, the Jetsnack one is called `JetsnackStyles`:
+
+
+   ```kotlin
+   object ExampleComponentStyles {
+       val customButtonStyle: Style = {
+
+       }
+       val customTextFieldStyle: Style = {
+
+       }
+   }
+   ```
+
+   <br />
+
+3. Expose this class through your custom theme with a static reference, don't
+   use `CompositionLocals` here as it's not required.
+
+
+   ```kotlin
+   @Immutable
+   class JetsnackTheme(
+       // other Design system properties
+   ) {
+       companion object {
+           val colors: CustomThemingWithStyles.JetsnackColors
+               @Composable @ReadOnlyComposable
+               get() = LocalJetsnackTheme.current.colors
+           // ...
+
+           // add helper static reference
+           val styles: ComponentStyles = ComponentStyles
+       }
+   }
+   ```
+
+   <br />
+
+4. Provide extensions on `StyleScope` to reference theme tokens directly if
+   they are exposed using `CompositionLocals`. For example:
+
+
+   ```kotlin
+   val StyleScope.colors: JetsnackColors
+       get() = LocalJetsnackTheme.currentValue.colors
+
+   val StyleScope.typography: androidx.compose.material3.Typography
+       get() = LocalJetsnackTheme.currentValue.typography
+
+   val StyleScope.shapes: Shapes
+       get() = LocalJetsnackTheme.currentValue.shapes
+   ```
+
+   <br />
+
+### Step 3: Migrate a component to Styles API
+
+For each custom component (for example, `CustomButton`), complete the following
+sequence:
+
+1. **Establish a visual baseline (If an emulator is available):**
+   - **If you CANNOT run an Android emulator:** Skip this step entirely and proceed to Step 2.
+   - **If you CAN run an Android emulator:** Perform the following to capture a baseline screenshot:
+     - **Option A:** Locate and run an existing screenshot test for the component.
+     - **Option B (If no test exists):** Create a test using the project's existing testing framework, then run it.
+     - **Option C (If no framework exists):** Create a minimal screenshot test using UI Automator or Espresso, then run it.
+2. **Remove individual styling parameters** : Remove styling parameters such as `backgroundColor`, `shape`, `textStyle`, and `contentPadding` from the signature - anything that `StyleScope` supports.
+3. **Add the style parameter** : Add `style: Style = Style` to the function signature. Always ensure the default value is exactly `Style` (e.g., `style:
+   Style = Style`) and not a specific style default like `ChipStyleDefault` or any other value.
+4. **Declare state tracking** : If the component is interactable, create a `MutableStyleState` using the interaction source. Update state fields (such as `isEnabled`) inside the Composable to track the state correctly.
+5. **Apply styleable modifier** : Replace specific layout modifiers on the root element with `Modifier.styleable()`.
+6. **Move defaults to ComponentStyles** : Move hardcoded values from the component definition to a dedicated `Style` instance in `ComponentStyles.kt`.
+7. **Validate component:** Compare the baseline screenshot image taken at the start with the rendered Compose Preview of the new composable. Ignore string content; focus on layout and styling. Iterate on the Compose code until visual parity is achieved. Once verified, write a Compose UI test for the new composable.
+
+#### Migration example
+
+Before Migration:
+
+
+```kotlin
+@Composable
+fun CustomButton(
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    backgroundColor: Color = JetsnackTheme.colors.brandLight,
+    disabledBackgroundColor: Color = JetsnackTheme.colors.brandSecondary,
+    shape: Shape = JetsnackTheme.shapes.extraLarge,
+    textStyle: TextStyle = JetsnackTheme.typography.labelLarge,
+    enabled: Boolean = true,
+    content: @Composable RowScope.() -> Unit,
+) {
+    val interactionSource = remember { MutableInteractionSource() }
+    Row(
+        modifier
+            .clickable(onClick = onClick, indication = null, interactionSource = interactionSource)
+            .background(if (enabled) backgroundColor else disabledBackgroundColor, shape)
+            .defaultMinSize(58.dp, 40.dp),
+        horizontalArrangement = Arrangement.Center,
+        verticalAlignment = Alignment.CenterVertically,
+        content = content,
+    )
+}
+```
+
+<br />
+
+After Migration:
+
+
+```kotlin
+// Exposed via ComponentStyles.kt
+object ComponentStyles {
+    val buttonStyle = Style {
+        background(colors.brandLight)
+        shape(shapes.extraLarge)
+        minWidth(58.dp)
+        minHeight(40.dp)
+        textStyle(typography.labelLarge)
+        disabled {
+            background(colors.brandSecondary)
+        }
+    }
+}
+
+@Composable
+fun CustomButton(
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    style: Style = Style,
+    enabled: Boolean = true,
+    content: @Composable RowScope.() -> Unit,
+) {
+    val interactionSource = remember { MutableInteractionSource() }
+    val styleState = rememberUpdatedStyleState(interactionSource) {
+        it.isEnabled = enabled
+    }
+    Row(
+        modifier
+            .clickable(onClick = onClick, indication = null, interactionSource = interactionSource)
+            .styleable(styleState, JetsnackTheme.styles.buttonStyle, style),
+        horizontalArrangement = Arrangement.Center,
+        verticalAlignment = Alignment.CenterVertically,
+        content = content,
+    )
+}
+```
+
+<br />
+
+### Step 4: Validate Changes
+
+1. Build the project. Verify that there are no compilation errors.
+2. Run your module's screenshot tests.
+3. Compare visual outputs of the whole app between the previous and updated components. Verify that no visual layout regressions occur.

package/skills/android-styles/references/android/develop/ui/compose/designsystems/custom.md

@@ -0,0 +1,459 @@
+While Material is our recommended design system and Jetpack Compose ships an
+implementation of Material, you are not forced to use it. Material is built
+entirely on public APIs, so it's possible to create your own design system in
+the same manner.
+
+There are several approaches you might take:
+
+- [Extend `MaterialTheme`](https://developer.android.com/develop/ui/compose/designsystems/custom#extending-material) with additional theming values.
+- [Replace one or more Material systems](https://developer.android.com/develop/ui/compose/designsystems/custom#replacing-systems) --- `Colors`, `Typography`, or `Shapes` --- with custom implementations while keeping the others.
+- [Implement a fully custom design system](https://developer.android.com/develop/ui/compose/designsystems/custom#implementing-fully-custom) to replace `MaterialTheme`.
+
+You may also want to continue using Material components with a custom design
+system. It's possible to do this but there are things to keep in mind to suit
+the approach you've taken.
+
+To learn more about the lower-level constructs and APIs used by `MaterialTheme`
+and custom design systems, check out the [Anatomy of a theme in Compose](https://developer.android.com/develop/ui/compose/designsystems/anatomy) guide.
+
+## Extend Material Theming
+
+Compose Material closely models
+[Material Theming](https://m3.material.io/)
+to make it straightforward and type-safe to follow the Material guidelines.
+However, it's possible to extend the color, typography, and shape sets with
+additional values. The simplest approach is to add extension properties:
+
+
+```kotlin
+// Use with MaterialTheme.colorScheme.snackbarAction
+val ColorScheme.snackbarAction: Color
+    @Composable
+    get() = if (isSystemInDarkTheme()) Red300 else Red700
+
+// Use with MaterialTheme.typography.textFieldInput
+val Typography.textFieldInput: TextStyle
+    get() = TextStyle(/* ... */)
+
+// Use with MaterialTheme.shapes.card
+val Shapes.card: Shape
+    get() = RoundedCornerShape(size = 20.dp)
+```
+
+<br />
+
+This provides consistency with `MaterialTheme` usage APIs. An example of this
+defined by Compose itself is
+[`surfaceColorAtElevation`](https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#(androidx.compose.material3.ColorScheme).surfaceColorAtElevation(androidx.compose.ui.unit.Dp)),
+which determines the surface color that should be used depending on the
+elevation.
+
+> [!NOTE]
+> **Note:** This approach is only recommended for straightforward theming value additions, or for values that are the same in different themes. If you have multiple themes, it's better to define a class with new properties instead.
+
+Another approach is to define an extended theme that "wraps" `MaterialTheme` and
+its values.
+
+Suppose you want to add two additional colors --- `caution` and `onCaution`, a
+yellow color used for actions that are semi-dangerous --- whilst keeping the
+existing Material colors:
+
+
+```kotlin
+@Immutable
+data class ExtendedColors(
+    val caution: Color,
+    val onCaution: Color
+)
+
+val LocalExtendedColors = staticCompositionLocalOf {
+    ExtendedColors(
+        caution = Color.Unspecified,
+        onCaution = Color.Unspecified
+    )
+}
+
+@Composable
+fun ExtendedTheme(
+    /* ... */
+    content: @Composable () -> Unit
+) {
+    val extendedColors = ExtendedColors(
+        caution = Color(0xFFFFCC02),
+        onCaution = Color(0xFF2C2D30)
+    )
+    CompositionLocalProvider(LocalExtendedColors provides extendedColors) {
+        MaterialTheme(
+            /* colors = ..., typography = ..., shapes = ... */
+            content = content
+        )
+    }
+}
+
+// Use with eg. ExtendedTheme.colors.caution
+object ExtendedTheme {
+    val colors: ExtendedColors
+        @Composable
+        get() = LocalExtendedColors.current
+}
+```
+
+<br />
+
+This is similar to `MaterialTheme` usage APIs. It also supports multiple themes
+as you can nest `ExtendedTheme`s in the same way as `MaterialTheme`.
+
+### Use Material components
+
+When extending Material Theming, existing `MaterialTheme` values are maintained
+and Material components still have reasonable defaults.
+
+If you want to use extended values in components, wrap them in your own
+composable functions, directly setting the values you want to alter, and
+exposing others as parameters to the containing composable:
+
+
+```kotlin
+@Composable
+fun ExtendedButton(
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    content: @Composable RowScope.() -> Unit
+) {
+    Button(
+        colors = ButtonDefaults.buttonColors(
+            containerColor = ExtendedTheme.colors.caution,
+            contentColor = ExtendedTheme.colors.onCaution
+            /* Other colors use values from MaterialTheme */
+        ),
+        onClick = onClick,
+        modifier = modifier,
+        content = content
+    )
+}
+```
+
+<br />
+
+You would then replace usages of `Button` with `ExtendedButton` where
+appropriate.
+
+
+```kotlin
+@Composable
+fun ExtendedApp() {
+    ExtendedTheme {
+        /*...*/
+        ExtendedButton(onClick = { /* ... */ }) {
+            /* ... */
+        }
+    }
+}
+```
+
+<br />
+
+## Replace Material subsystems
+
+Instead of extending Material Theming, you may want to replace one or more
+systems --- `Colors`, `Typography`, or `Shapes` --- with a custom implementation,
+while maintaining the others.
+
+Suppose you want to replace the type and shape systems while keeping the color
+system:
+
+
+```kotlin
+@Immutable
+data class ReplacementTypography(
+    val body: TextStyle,
+    val title: TextStyle
+)
+
+@Immutable
+data class ReplacementShapes(
+    val component: Shape,
+    val surface: Shape
+)
+
+val LocalReplacementTypography = staticCompositionLocalOf {
+    ReplacementTypography(
+        body = TextStyle.Default,
+        title = TextStyle.Default
+    )
+}
+val LocalReplacementShapes = staticCompositionLocalOf {
+    ReplacementShapes(
+        component = RoundedCornerShape(ZeroCornerSize),
+        surface = RoundedCornerShape(ZeroCornerSize)
+    )
+}
+
+@Composable
+fun ReplacementTheme(
+    /* ... */
+    content: @Composable () -> Unit
+) {
+    val replacementTypography = ReplacementTypography(
+        body = TextStyle(fontSize = 16.sp),
+        title = TextStyle(fontSize = 32.sp)
+    )
+    val replacementShapes = ReplacementShapes(
+        component = RoundedCornerShape(percent = 50),
+        surface = RoundedCornerShape(size = 40.dp)
+    )
+    CompositionLocalProvider(
+        LocalReplacementTypography provides replacementTypography,
+        LocalReplacementShapes provides replacementShapes
+    ) {
+        MaterialTheme(
+            /* colors = ... */
+            content = content
+        )
+    }
+}
+
+// Use with eg. ReplacementTheme.typography.body
+object ReplacementTheme {
+    val typography: ReplacementTypography
+        @Composable
+        get() = LocalReplacementTypography.current
+    val shapes: ReplacementShapes
+        @Composable
+        get() = LocalReplacementShapes.current
+}
+```
+
+<br />
+
+### Use Material components
+
+When one or more systems of `MaterialTheme` have been replaced, using Material
+components as-is may result in unwanted Material color, type, or shape values.
+
+If you want to use replacement values in components, wrap them in your own
+composable functions, directly setting the values for the relevant system, and
+exposing others as parameters to the containing composable.
+
+> [!NOTE]
+> **Note:** Not all values may be exposed as parameters in Material composables, in particular with `CompositionLocal` composables (such as `LocalTextStyle`). In such cases you may need to wrap `content` lambdas in provider functions (like `ProvideTextStyle`).
+
+
+```kotlin
+@Composable
+fun ReplacementButton(
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    content: @Composable RowScope.() -> Unit
+) {
+    Button(
+        shape = ReplacementTheme.shapes.component,
+        onClick = onClick,
+        modifier = modifier,
+        content = {
+            ProvideTextStyle(
+                value = ReplacementTheme.typography.body
+            ) {
+                content()
+            }
+        }
+    )
+}
+```
+
+<br />
+
+You would then replace usages of `Button` with `ReplacementButton` where
+appropriate.
+
+
+```kotlin
+@Composable
+fun ReplacementApp() {
+    ReplacementTheme {
+        /*...*/
+        ReplacementButton(onClick = { /* ... */ }) {
+            /* ... */
+        }
+    }
+}
+```
+
+<br />
+
+## Implement a fully custom design system
+
+You may want to replace Material Theming with a fully custom design system.
+Consider that `MaterialTheme` provides the following systems:
+
+- `Colors`, `Typography`, and `Shapes`: Material Theming systems
+- `TextSelectionColors`: Colors used for text selection by `Text` and `TextField`
+- `Ripple` and `RippleTheme`: Material implementation of `Indication`
+
+If you want to continue using Material components, you must replace some of
+these systems in your custom themes or handle the systems in your
+components to avoid unwanted behavior.
+
+However, design systems are not limited to the concepts Material relies on. You
+can modify existing systems and introduce entirely new ones --- with new classes
+and types --- to make other concepts compatible with themes.
+
+In the following code, we model a custom color system that includes gradients
+(`List<Color>`), include a type system, introduce a new elevation system,
+and exclude other systems provided by `MaterialTheme`:
+
+![Screenshot of a mobile app UI demonstrating a custom design system with elements using gradients for colors, custom typography, and elevation.](https://developer.android.com/static/develop/ui/compose/images/themes/custom-color-gradients.png)
+
+
+```kotlin
+@Immutable
+data class CustomColors(
+    val content: Color,
+    val component: Color,
+    val background: List<Color>
+)
+
+@Immutable
+data class CustomTypography(
+    val body: TextStyle,
+    val title: TextStyle
+)
+
+@Immutable
+data class CustomElevation(
+    val default: Dp,
+    val pressed: Dp
+)
+
+val LocalCustomColors = staticCompositionLocalOf {
+    CustomColors(
+        content = Color.Unspecified,
+        component = Color.Unspecified,
+        background = emptyList()
+    )
+}
+val LocalCustomTypography = staticCompositionLocalOf {
+    CustomTypography(
+        body = TextStyle.Default,
+        title = TextStyle.Default
+    )
+}
+val LocalCustomElevation = staticCompositionLocalOf {
+    CustomElevation(
+        default = Dp.Unspecified,
+        pressed = Dp.Unspecified
+    )
+}
+
+@Composable
+fun CustomTheme(
+    /* ... */
+    content: @Composable () -> Unit
+) {
+    val customColors = CustomColors(
+        content = Color(0xFFDD0D3C),
+        component = Color(0xFFC20029),
+        background = listOf(Color.White, Color(0xFFF8BBD0))
+    )
+    val customTypography = CustomTypography(
+        body = TextStyle(fontSize = 16.sp),
+        title = TextStyle(fontSize = 32.sp)
+    )
+    val customElevation = CustomElevation(
+        default = 4.dp,
+        pressed = 8.dp
+    )
+    CompositionLocalProvider(
+        LocalCustomColors provides customColors,
+        LocalCustomTypography provides customTypography,
+        LocalCustomElevation provides customElevation,
+        content = content
+    )
+}
+
+// Use with eg. CustomTheme.elevation.small
+object CustomTheme {
+    val colors: CustomColors
+        @Composable
+        get() = LocalCustomColors.current
+    val typography: CustomTypography
+        @Composable
+        get() = LocalCustomTypography.current
+    val elevation: CustomElevation
+        @Composable
+        get() = LocalCustomElevation.current
+}
+```
+
+<br />
+
+### Use Material components
+
+When no `MaterialTheme` is present, using Material components as-is will result
+in unwanted Material color, type, and shape values and indication behavior.
+
+If you want to use custom values in components, wrap them in your own composable
+functions, directly setting the values for the relevant system, and exposing
+others as parameters to the containing composable.
+
+We recommend that you access values you set from your custom theme.
+Alternatively, if your theme doesn't provide `Color`, `TextStyle`, `Shape`, or
+other systems, you can hardcode them.
+
+
+```kotlin
+@Composable
+fun CustomButton(
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    content: @Composable RowScope.() -> Unit
+) {
+    Button(
+        colors = ButtonDefaults.buttonColors(
+            containerColor = CustomTheme.colors.component,
+            contentColor = CustomTheme.colors.content,
+            disabledContainerColor = CustomTheme.colors.content
+                .copy(alpha = 0.12f)
+                .compositeOver(CustomTheme.colors.component),
+            disabledContentColor = CustomTheme.colors.content
+                .copy(alpha = 0.38f)
+
+        ),
+        shape = ButtonShape,
+        elevation = ButtonDefaults.elevatedButtonElevation(
+            defaultElevation = CustomTheme.elevation.default,
+            pressedElevation = CustomTheme.elevation.pressed
+            /* disabledElevation = 0.dp */
+        ),
+        onClick = onClick,
+        modifier = modifier,
+        content = {
+            ProvideTextStyle(
+                value = CustomTheme.typography.body
+            ) {
+                content()
+            }
+        }
+    )
+}
+
+val ButtonShape = RoundedCornerShape(percent = 50)
+```
+
+<br />
+
+> [!NOTE]
+> **Note:** `Button` uses `rememberRipple()` internally to provide a `Ripple` `Indication`. It's a good idea to check the source code when implementing other custom components that wrap existing components.
+
+If you've introduced new class types --- such as `List<Color>` to represent
+gradients --- then it may be better to implement components from scratch instead
+of wrapping them. For an example, take a look at
+[`JetsnackButton`](https://github.com/android/compose-samples/blob/main/Jetsnack/app/src/main/java/com/example/jetsnack/ui/components/Button.kt)
+from the Jetsnack sample.
+
+## Recommended for you
+
+- Note: link text is displayed when JavaScript is off
+- [Material Design 3 in Compose](https://developer.android.com/develop/ui/compose/designsystems/material3)
+- [Migrate from Material 2 to Material 3 in Compose](https://developer.android.com/develop/ui/compose/designsystems/material2-material3)
+- [Anatomy of a theme in Compose](https://developer.android.com/develop/ui/compose/designsystems/anatomy)