mad-pro-cli 1.0.0

package/templates/mad-skills/references/cmp_migration.md

@@ -0,0 +1,56 @@
+# Migrating from Jetpack Compose to Compose Multiplatform (CMP)
+
+Compose Multiplatform (CMP) allows you to use your Jetpack Compose UI skills to build applications for iOS, Web, and Desktop.
+
+## 1. The Migration Workflow
+
+Once your project has a KMP module (see [KMP Migration](file:///Users/denirohimat/Works/JetpackComposeSkills/references/kmp_migration.md)), you can start sharing your UI.
+
+### Phase 1: Dependency Update
+
+- Change your Gradle dependencies from `androidx.compose.*` to the multiplatform equivalent `org.jetbrains.compose.*`.
+- Use the **Compose Multiplatform Gradle Plugin** to manage versions across platforms.
+
+### Phase 2: Move UI to `commonMain`
+
+- Move your `@Composable` functions from the `:app` module (Android) to the `commonMain` source set of your shared module.
+- **Goal**: Keep as much UI logic in `commonMain` as possible.
+
+### Phase 3: Replacement of Android-Specific APIs
+
+Replace Android-only APIs with their KMP/CMP equivalents:
+
+- **Resources**: Replace `R.string.*` or `R.drawable.*` with **library-based resource management** (e.g., `Moko-Resources` or the built-in CMP resources API).
+- **ViewModels**: Use **KMP ViewModels** (e.g., from `androidx.lifecycle` KMP support or `Decompose`).
+- **Navigation**: Switch to multiplatform navigation libraries like **Compose-Navigation (Multiplatform)**, **Voyager**, or **Decompose**.
+
+## 2. Platform-Specific UI: `expect/actual`
+
+Sometimes you need a native UI component (e.g., a Google Map or a specialized iOS picker).
+
+- **Expect**: Define a `Composable` interface in `commonMain`.
+- **Actual (Android)**: Implement using `AndroidView` to wrap existing native views.
+- **Actual (iOS)**: Implement using `UIKitView` to wrap UIKit/SwiftUI components.
+
+## 3. Handling Graphics and Interop
+
+- **Canvas**: CMP supports a common Canvas API across all platforms.
+- **Images**: Ensure images are in formats supported by all platforms (WebP, PNG, SVG).
+- **Fonts**: Bundle custom fonts in the shared module to ensure consistent typography.
+
+## 4. Migration Checklist
+
+- [ ] Compose Multiplatform plugin applied?
+- [ ] Dependencies switched to `org.jetbrains.compose`?
+- [ ] UI components moved to `commonMain`?
+- [ ] Resources (Strings/Images) migrated to multiplatform-ready API?
+- [ ] Navigation replaced with multiplatform solution?
+- [ ] ViewModels updated to support KMP?
+
+## 5. Next Steps
+
+After migrating the UI, test on different targets:
+
+- **iOS**: Run using the `iosApp` target in Android Studio or Xcode.
+- **Desktop**: Run using `./gradlew :shared:run`.
+- **Web**: Run using `./gradlew :shared:jsBrowserDevelopmentRun`.

package/templates/mad-skills/references/concurrency.md

@@ -0,0 +1,50 @@
+# Concurrency and Flow in Jetpack Compose
+
+Kotlin Coroutines and Flow are the lifeblood of asynchronous programming in modern Android development.
+
+## 1. Collecting Flow Safely
+
+**NEVER** use `collectAsState()` in production. Always use `collectAsStateWithLifecycle()` to ensure collection stops when the app is in the background.
+
+```kotlin
+val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+```
+
+*Requires `androidx.lifecycle:lifecycle-runtime-compose` dependency.*
+
+## 2. Side Effect APIs
+
+- **`LaunchedEffect`**: Runs a coroutine when a "key" changes. If the key is `Unit`, it runs once when the composable enters the composition.
+- **`rememberCoroutineScope`**: Returns a scope tied to the composition lifecycle. Use this for firing coroutines in response to user events (like button clicks).
+- **`DisposableEffect`**: Used for setup/teardown logic (e.g., registering listeners).
+
+```kotlin
+val scope = rememberCoroutineScope()
+Button(onClick = {
+    scope.launch { /* trigger long running task */ }
+}) { ... }
+```
+
+## 3. Best Practices for Coroutines
+
+- **Main-Safe ViewModels**: All ViewModel functions should be "main-safe". The ViewModel is responsible for choosing the correct Dispatcher (usually `Dispatchers.IO` for background tasks).
+- **Avoid GlobalScope**: Always use `viewModelScope` or `rememberCoroutineScope` to ensure tasks are canceled when no longer needed.
+- **Flow Operators**: Use `onEach`, `map`, and `filter` in the ViewModel to transform data before it reaches the UI.
+
+## 4. Derived State and Flow
+
+If you have a Flow that depends on another Flow, use `combine` or `flatMapLatest` in the ViewModel.
+
+```kotlin
+val filteredData = combine(searchQuery, rawData) { query, data ->
+    data.filter { it.contains(query) }
+}.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
+```
+
+## 5. Threading Rule
+
+- **Composition**: Must be on the Main Thread.
+- **Business Logic/Data**: Should be on background threads (managed by the Repository/ViewModel).
+- **State Updates**: Updates to `MutableStateFlow` or Compose `State` are thread-safe, but usually happen on the Main Thread.
+
+## 6. Threading Rule

package/templates/mad-skills/references/deeplinks.md

@@ -0,0 +1,42 @@
+# Deep Links and App Links
+
+Deep links allow users to navigate directly to a specific part of your app from an external source (Email, Website, SMS).
+
+## 1. Traditional Deep Links
+
+Easy to implement but not exclusive to your app. Multiple apps might try to handle the same URI.
+
+- **Scheme**: e.g., `myapp://product/123`.
+- **Implementation**: Define an `<intent-filter>` in `AndroidManifest.xml`.
+
+## 2. Android App Links (Verified Deep Links)
+
+The most secure way to handle links. These are verified against a web domain you own.
+
+- **Security**: Ensures that only your app can handle your website's URLs.
+- **UX**: Opens the app directly without showing the "Disambiguation Dialog".
+- **Verification**: Requires a `assetlinks.json` file hosted on your website at `.well-known/assetlinks.json`.
+
+## 3. Navigation Component Integration
+
+Integration with the Jetpack Navigation library makes Deep Linking seamless.
+
+```kotlin
+composable(
+    route = "product/{id}",
+    deepLinks = listOf(navDeepLink { uriPattern = "https://www.myapp.com/product/{id}" })
+) { backStackEntry ->
+    val id = backStackEntry.arguments?.getString("id")
+    ProductScreen(productId = id)
+}
+```
+
+## 4. Handling Parameters
+
+- **Type Safety**: Use the default navigation arguments to parse IDs or tokens.
+- **Fallback**: Always provide a fallback (e.g., Home Screen) if the deep link parameters are malformed or the resource no longer exists.
+
+## 4. Security Considerations
+
+- **Input Validation**: Treat all deep link data as "untrusted". Validate strings, IDs, and tokens before using them.
+- **Authentication**: Ensure that sensitive screens (like "Change Password") still require a valid session even if opened via a deep link.

package/templates/mad-skills/references/design_principles.md

@@ -0,0 +1,47 @@
+# Jetpack Compose Design Principles
+
+Compose isn't just a new UI toolkit; it's a shift in how we think about building UIs.
+
+## 1. Declarative over Imperative
+
+- **Imperative**: You manually mutate the UI state (e.g., `textView.text = "Hello"`). You manage the transition between states.
+- **Declarative**: You describe what the UI should look like for a given state. Compose handles the transitions (recomposition) automatically.
+
+## 2. Composition over Inheritance
+
+Compose favors shallow hierarchies of reusable components rather than deep class inheritance.
+
+- **Slot API**: Instead of extending a class, pass a `@Composable` lambda to a "slot" to customize content.
+- **Small Components**: Build complex UIs by combining many small, single-purpose composables.
+
+## 3. Unidirectional Data Flow (UDF)
+
+- **State flows down**: The parent provides data to the child via parameters.
+- **Events flow up**: The child notifies the parent of user interactions via lambdas.
+
+This makes the UI predictable, easier to test, and reduces bugs related to state synchronization.
+
+## 4. Pure & Stateless Composables
+
+A good composable should ideally be a "pure function" of its arguments.
+
+- **Stateless**: The composable doesn't manage its own state; it receives it (State Hoisting).
+- **Side-Effect Free**: Recomposition can happen many times. Never perform business logic, network calls, or database writes directly inside a composable function. Use `LaunchedEffect` or `produceState`.
+
+## 5. Single Source of Truth
+
+State should live in one place (usually a `ViewModel`). Any piece of data should have exactly one "owner" who is responsible for updating it.
+
+## 6. Stability and Idempotence
+
+- **Stable**: If the inputs haven't changed, the output (UI) shouldn't change.
+- **Idempotent**: Running the same composable with the same parameters should always produce the same result and have no side effects.
+
+## Why it Matters
+
+Following these principles leads to:
+
+1. **Less Code**: Declarative UI is often much more concise than XML.
+2. **Fewer Bugs**: UDF eliminates entire classes of state-synchronization bugs.
+3. **Easier Testing**: Pure functions are straightforward to unit test.
+4. **Better Performance**: Compose can skip recomposition for stable, unchanged components.

package/templates/mad-skills/references/design_systems.md

@@ -0,0 +1,47 @@
+# Design Systems at Scale
+
+A professional Design System goes beyond basic theming. It provides a common language between designers and developers.
+
+## 1. Design Tokens
+
+Tokens are the smallest pieces of the design system: colors, spacing, typography, and elevation stored as data.
+
+### Standard Token Structure
+
+- **Primitive Tokens**: `blue-500`, `spacing-16`.
+- **Semantic Tokens**: `color-primary`, `spacing-medium`.
+- **Component Tokens**: `button-background-color`.
+
+## 2. Shared Component Library
+
+Encapsulate Material 3 components into your own brand-specific wrappers to ensure consistency.
+
+```kotlin
+@Composable
+fun MadButton(
+    text: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true
+) {
+    Button(
+        onClick = onClick,
+        modifier = modifier,
+        enabled = enabled,
+        shape = MadTheme.shapes.button, // Custom shape from tokens
+        colors = ButtonDefaults.buttonColors(
+            containerColor = MadTheme.colors.primary
+        )
+    ) {
+        Text(text = text, style = MadTheme.typography.label)
+    }
+}
+```
+
+## 3. Documentation (Showcase)
+
+Create a "Catalog" or "Showcase" app within your project to view and test components in isolation.
+
+- Use **Compose Previews** extensively with different configurations (Dark mode, Large font).
+- Consider tools like **Showkase** to automatically generate a component browser.
+- Use **Screenshot Testing** (Paparazzi or Roborazzi) to prevent visual regressions.

package/templates/mad-skills/references/domain_layer.md

@@ -0,0 +1,47 @@
+# Domain Layer in Modern Android Development
+
+The Domain Layer is an optional layer that sits between the UI and Data layers. It is responsible for encapsulating complex business logic or logic that is reused by multiple ViewModels.
+
+## 1. The Role of the Domain Layer
+
+- **Simplification**: Simplifies ViewModels by removing business logic.
+- **Reusability**: Allows sharing logic across different screens (e.g., calculating a complex price).
+- **Testability**: Makes business logic easy to unit test without dependencies on Android classes or UI.
+
+## 2. Use Cases
+
+The primary component of the Domain Layer is the `UseCase` (often called an Interactor).
+
+### Naming Convention
+
+A Use Case should be named after the action it performs: `Verb` + `Noun` + `UseCase`.
+Example: `GetUserDataUseCase`, `ValidateEmailUseCase`.
+
+### Implementation
+
+Each Use Case should typically perform only **one** task and expose a single public function (usually using the `operator fun invoke`).
+
+```kotlin
+class GetUserUseCase @Inject constructor(
+    private val userRepository: UserRepository
+) {
+    operator fun invoke(userId: String): Flow<User> {
+        return userRepository.getUser(userId)
+    }
+}
+```
+
+## 3. When to Use a Domain Layer
+
+You don't always need a Domain Layer. Google recommends adding it only when:
+
+1. **Logic is complex**: E.g., data from multiple repositories needs to be combined.
+2. **Logic is reused**: E.g., multiple ViewModels need to perform the same validation.
+3. **Purity is desired**: You want to keep your domain logic purely in Kotlin, away from the Data layer's implementation details.
+
+## 4. Best Practices
+
+- **Stateless**: Use Cases should be stateless. Any state should be managed by the UI or Data layers.
+- **Dependency Direction**: The Domain layer depends on the Data layer's **interfaces** (abstractions), not its implementations.
+- **Single Source of Truth**: Use Cases should not maintain their own cache; they should rely on the Data layer for that.
+- **Error Handling**: Use Cases can catch data-layer-specific exceptions and map them to domain-specific errors.

package/templates/mad-skills/references/google_play_skills.md

@@ -0,0 +1,40 @@
+# Google Play Skills and Compliance
+
+Publishing an app successfully requires adhering to Google Play policies and ensuring technical quality.
+
+## 1. App Quality & Performance
+
+Google Play prioritizes apps that are stable and performant.
+
+- **Vitals**: Monitor Android Vitals in the Play Console to track crash rates and ANRs (Application Not Responding).
+- **Frame Rate**: Ensure your Compose UI hits 60fps (or 120fps on capable screens) to avoid "jank" that lowers your store ranking.
+
+## 2. Policy Compliance
+
+- **Data Safety**: Be transparent about data collection. Every app must have a Privacy Policy URL.
+- **Permissions**: Only request "dangerous" permissions that are essential for the app's core functionality. Explain clearly to the user why they are needed (Requirement: Data Safety Section).
+- **Sensitive Content**: Adhere to content ratings and avoid restricted content (e.g., hate speech, illegal acts).
+
+## 3. Technical Requirements
+
+- **Android App Bundle (AAB)**: Google Play now requires the `.aab` format instead of `.apk` for new apps. This allows for dynamic delivery and smaller download sizes.
+- **Target API Level**: Keep your app updated. Google Play requires apps to target a recent API level (usually within 1 year of the latest release).
+- **Play Integrity API**: Use this to ensure your app is running on a genuine device and hasn't been tampered with (crucial for games and financial apps).
+
+## 4. App Store Optimization (ASO)
+
+- **Keywords**: Use relevant terms in your title and short description.
+- **Visuals**: High-quality screenshots and a compelling feature graphic significantly increase conversion rates.
+- **Localization**: Localize your store listing and in-app text for your main target markets.
+
+## 5. Release Management
+
+- **Internal Testing**: Use Internal Testing tracks for quick feedback from your team.
+- **Staged Rollouts**: Deploy updates to a small percentage of users (e.g., 1%, 10%) first to catch unforeseen bugs early.
+- **Review Management**: Respond to user reviews professionally; this improves user trust and can lead to better ratings.
+
+## 6. Best Practices for Developers
+
+- **API Deprecation**: Monitor the Android Developers blog for upcoming API changes or deprecations.
+- **ProGuard/R8**: Always enable R8 in your release builds to shrink and obfuscate your code, reducing app size and protecting your IP.
+- **Firebase App Distribution**: Use this for pre-release testing before moving to Play Console tracks.

package/templates/mad-skills/references/kmp_migration.md

@@ -0,0 +1,62 @@
+# Migrating from Native Android to Kotlin Multiplatform (KMP)
+
+Migrating an existing Android project to KMP allows you to share business logic with iOS, Web, and Desktop while keeping your existing Android UI.
+
+## 1. The Migration Strategy: "Data-First"
+
+The most successful migrations follow a bottom-up approach, starting with the data layer.
+
+### Phase 1: Preparation
+
+- **Modularize**: Ensure your app has a clear separation between UI and Data/Domain.
+- **Dependency Audit**: Identify libraries that don't support KMP (e.g., standard Room, Retrofit, Glide). Find KMP alternatives (Ktor, SQLDelight/Room-KMP).
+
+### Phase 2: Create the Shared Module
+
+- Add a new `KMP Shared Module` to your project (usually named `:shared` or `:common`).
+- Configure `commonMain`, `androidMain`, and `iosMain` source sets in `build.gradle.kts`.
+
+### Phase 3: Migrate Data Models
+
+- Move your POJOs/Data Classes to `commonMain`.
+- Ensure they only use Kotlin standard libraries (no `android.*` imports).
+
+### Phase 4: Migrate Networking & Persistence
+
+- Replace Retrofit with **Ktor**.
+- Replace Room with **SQLDelight** or use the new **Room-KMP** version.
+- Move Repositories to `commonMain`.
+
+### Phase 5: Domain Layer Migration
+
+- Move Use Cases and business logic to `commonMain`.
+- Use `expect/actual` for platform-specific logic (e.g., getting a device ID or logging).
+
+## 2. Handling Android-Specific Dependencies
+
+If a class depends on `Context`, you have two choices:
+
+1. **Remove the dependency**: Refactor the class to not need `Context`.
+2. **Inject from Android**: Define an interface in `commonMain` and provide the implementation in `androidMain` using the Android `Context`.
+
+## 3. Integration with iOS
+
+Once the shared module is ready:
+
+- Connect the shared module to an Xcode project using the `KMP CocoaPods plugin` or `Swift Package Manager (SPM)`.
+- Call the shared Repositories/Use Cases from SwiftUI.
+
+## 4. Common Pitfalls
+
+- **Avoid `android.*` in Shared**: Using any Android-specific library in `commonMain` will break the iOS build.
+- **Serialization**: Use `kotlinx-serialization` instead of GSON or Moshi if you want to share models.
+- **Concurrency**: Use `Flow` as the bridge between Kotlin and Swift (with SKIE for better compatibility).
+
+## 5. Migration Checklist
+
+- [ ] Project modularized by layer?
+- [ ] KMP shared module created?
+- [ ] Networking moved to Ktor?
+- [ ] Database moved to SQLDelight/Room-KMP?
+- [ ] Business logic (Use Cases) in `commonMain`?
+- [ ] iOS project consuming shared code?

package/templates/mad-skills/references/layouts.md

@@ -0,0 +1,57 @@
+# Layouts and Structure
+
+Jetpack Compose provides powerful tools for building flexible and responsive layouts.
+
+## Fundamental Components
+
+1. **`Scaffold`**: Always use `Scaffold` as the root of a screen to handle Top Bars, Bottom Bars, and Snackbars.
+2. **`Column` / `Row`**: The primary building blocks for vertical and horizontal alignment.
+3. **`Box`**: Use for overlapping content or centering elements.
+4. **`LazyColumn` / `LazyRow`**: Essential for lists with many items to ensure performance.
+
+## Best Practices
+
+- **Weight**: Use `Modifier.weight()` within Columns and Rows to distribute space proportionally.
+- **Content Padding**: Use `PaddingValues` in Lazy lists instead of adding padding to individual items to avoid clipping issues.
+- **Intrinsics**: Avoid fixed heights where possible; use `Modifier.height(IntrinsicSize.Min/Max)` if you need components to match heights.
+
+## Responsive Design
+
+- Use `Adaptive` layouts for larger screens.
+- Check `WindowWidthSizeClass` to switch between Navigation Rail (Tablet/Desktop) and Bottom Navigation (Mobile).
+
+## Example: Standard Screen Structure
+
+```kotlin
+@Composable
+fun MyScreen(
+    uiState: MyUiState,
+    onBackClick: () -> Unit
+) {
+    Scaffold(
+        topBar = {
+            TopAppBar(
+                title = { Text("Title") },
+                navigationIcon = {
+                    IconButton(onClick = onBackClick) {
+                        Icon(Icons.Default.ArrowBack, contentDescription = null)
+                    }
+                }
+            )
+        }
+    ) { innerPadding ->
+        Column(
+            modifier = Modifier
+                .padding(innerPadding)
+                .fillMaxSize()
+        ) {
+            // Content here
+        }
+    }
+}
+```
+
+## 5. Optimization
+
+- Use `LazyColumn` keys (`items(items, key = { it.id })`) to help Compose maintain state during list updates.
+- Use `contentType` in Lazy lists to help with view recycling efficiency.

package/templates/mad-skills/references/local_data.md

@@ -0,0 +1,53 @@
+# Local Data Persistence in Jetpack Compose
+
+Handling persistent data correctly ensures a seamless offline-first experience.
+
+## 1. Room Database
+
+Room is the recommended way to handle structured local data.
+
+**Pattern**: Expose data as a `Flow` in the DAO.
+
+```kotlin
+@Dao
+interface UserDao {
+    @Query("SELECT * FROM users")
+    fun getAllUsers(): Flow<List<User>>
+}
+```
+
+**Consumption in Compose**:
+
+```kotlin
+val users by viewModel.usersFlow.collectAsStateWithLifecycle(initialValue = emptyList())
+```
+
+## 2. DataStore (Preferences)
+
+Use DataStore instead of SharedPreferences for simple key-value pairs.
+
+- **Async/Safe**: It uses Coroutines and handles data updates atomically.
+- **State Integration**: Since it exposes a `Flow`, it integrates perfectly with Compose.
+
+```kotlin
+val settingsFlow: Flow<UserSettings> = context.dataStore.data
+    .map { preferences ->
+        UserSettings(theme = preferences[THEME_KEY] ?: "light")
+    }
+```
+
+## 3. Offline-First Architecture
+
+A standard offline-first app follows this flow:
+
+1. UI requests data from the ViewModel.
+2. ViewModel observes a Flow from the Repository (which observes the Room DB).
+3. Repository triggers a network sync if needed and saves the result to Room.
+4. Room automatically emits the new data to the Flow, updating the UI.
+
+## 4. Best Practices
+
+- **Never block the Main Thread**: Room and DataStore operations should always run on `Dispatchers.IO`.
+- **Encrypted DataStore**: Use encryption for sensitive settings.
+- **Migration**: Always provide a `Migration` strategy when changing your database schema to avoid app crashes.
+- **Single Instance**: Ensure you use a single instance of your Room Database (usually via Hilt/Koin).

package/templates/mad-skills/references/migration_xml_to_compose.md

@@ -0,0 +1,80 @@
+# Migration from XML to Jetpack Compose
+
+Migrating a legacy application to Jetpack Compose should be a gradual process, not a "big bang" rewrite.
+
+## Gradual Migration Strategies
+
+1. **New Features in Compose**: Build all new screens and features using Compose.
+2. **Bottom-Up**: Start by migrating small, leaf-level components (buttons, text fields).
+3. **Top-Down**: Migrate entire screens at once by replacing the Fragment/Activity layout with a `ComposeView`.
+
+## Interoperability APIs
+
+### Using Compose in XML (`ComposeView`)
+
+To add Compose to an existing XML layout, use `ComposeView`.
+
+**XML Layout:**
+
+```xml
+<LinearLayout ...>
+    <androidx.compose.ui.platform.ComposeView
+        android:id="@+id/compose_view"
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content" />
+</LinearLayout>
+```
+
+**Activity/Fragment:**
+
+```kotlin
+binding.composeView.apply {
+    setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
+    setContent {
+        M3Theme {
+            MyComposeComponent()
+        }
+    }
+}
+```
+
+### Using Views in Compose (`AndroidView`)
+
+If you need a component that doesn't exist in Compose yet (e.g., `MapView`, `WebView`), use `AndroidView`.
+
+```kotlin
+@Composable
+fun LegacyWebView(url: String) {
+    AndroidView(
+        factory = { context ->
+            WebView(context).apply {
+                webViewClient = WebViewClient()
+            }
+        },
+        update = { webView ->
+            webView.loadUrl(url)
+        }
+    )
+}
+```
+
+## Theme Interop
+
+Use the **Material Theme Adapter** library to bridge your existing XML XML (MDC/AppCompat) theme with `MaterialTheme` in Compose.
+
+```kotlin
+MdcTheme { // Automatically inherits colors from your XML theme
+    MyScreen()
+}
+```
+
+## 4. Navigation Interop
+
+- **Fragment to Compose**: Use `findNavController().navigate(R.id.compose_fragment)`.
+- **Compose to Fragment**: If using `NavHost` in Compose, you can still navigate to deep links that are handled by your existing Fragment-based navigation.
+
+## 5. Best Practices
+
+- **Avoid Hybrid State**: Do not share `MutableState` directly between Views and Composables. Use `ViewModel` as the single source of truth.
+- **Dispose Correctly**: Always set a `ViewCompositionStrategy` to avoid memory leaks in Fragments.
+- **Standardize UI**: Migrating is a great time to audit your design system and ensure consistency.

package/templates/mad-skills/references/modifiers.md

@@ -0,0 +1,46 @@
+# Modifiers in Jetpack Compose
+
+Modifiers allow you to decorate or augment composables. They are the primary way to style and position elements.
+
+## Rule of Order
+
+**ORDER MATTERS.** Modifiers are applied from left to right (or top to bottom in code).
+
+- `Modifier.padding(10.dp).background(Color.Red)` -> Background is applied *after* padding.
+- `Modifier.background(Color.Red).padding(10.dp)` -> Padding is applied *inside* the background.
+
+## Standard Order Recommendation
+
+1. Sizing (`fillMaxSize`, `size`, `height`, `width`)
+2. Padding
+3. Background / Border / Shape
+4. Constraints or Offsets
+5. Interaction handlers (`clickable`, `toggleable`)
+
+## Best Practices
+
+- **Pass a Modifier**: Every reusable composable should accept a `modifier: Modifier = Modifier` parameter as its first optional argument.
+- **Consumer Ownership**: Let the caller decide the size and outer padding of your component.
+- **`clickable` vs `IconButton`**: Use `IconButton` for simple icon buttons. Use `Modifier.clickable` for custom layouts, ensuring you use `indication` and `interactionSource` for proper visual feedback (Ripples).
+
+## Reusability Pattern
+
+```kotlin
+@Composable
+fun MyComponent(
+    modifier: Modifier = Modifier
+) {
+    Box(
+        modifier = modifier
+            .background(Color.Gray)
+            .padding(16.dp)
+    ) {
+        // ...
+    }
+}
+```
+
+## 4. Advanced Usage
+
+- **`graphicsLayer`**: Use for efficient rotations, scaling, and opacity changes without triggering recomposition as often.
+- **Custom Modifiers**: Avoid overusing them; usually, a simple extension function on `Modifier` is enough.