Add docs for Android components

docs/_partials/android/customization.mdx

@@ -0,0 +1,3 @@
+To learn how to customize Clerk Android views, see the [dedicated guide](/docs/reference/android/clerk-theme).
+
+If Clerk's prebuilt views don't meet your specific needs or if you require more control over the logic, you can rebuild the existing Clerk flows using the Clerk API. For more information, see the [custom flow guides](/docs/guides/development/custom-flows/overview).

docs/reference/android/clerk-theme.mdx

@@ -0,0 +1,279 @@
+---
+title: '`ClerkTheme`'
+description: Utilize Clerk's ClerkTheme to adjust the general styles of the Android views, like colors, fonts, and design properties.
+sdk: android
+---
+
+The `ClerkTheme` is used to customize the appearance of Clerk iOS views by adjusting colors, fonts, and design properties. It provides a comprehensive theming system that allows you to create a consistent visual experience across all Clerk views.
+
+## Structure
+
+`ClerkTheme` consists of 5 main properties:
+
+- **`colors`** - Colors used by the UI layer across light and dark modes.
+- **`lightColors`** - Optional overrides that only apply when the system is in light mode. These will default to the `colors` property if not provided.
+- **`darkColors`** - Optional overrides that only apply when the system is in dark mode. These will default to the `colors` property if not provided.
+- **`typography`** - Font and typography definitions..
+- **`design`** - Design properties like border radius.
+
+## Colors
+
+The `colors`,`lightColors`, and `darkColors` properties contain the following color options:
+
+<Properties>
+  - `primary`
+  - `Color`
+
+  The primary color used throughout the views.
+
+  ---
+
+  - `background`
+  - `Color`
+
+  The background color for containers.
+
+  ---
+
+  - `input`
+  - `Color`
+
+  The background color used for input fields.
+
+  ---
+
+  - `danger`
+  - `Color`
+
+  The color used for error states.
+
+  ---
+
+  - `success`
+  - `Color`
+
+  The color used for success states.
+
+  ---
+
+  - `warning`
+  - `Color`
+
+  The color used for warning states.
+
+  ---
+
+  - `foreground`
+  - `Color`
+
+  The color used for text.
+
+  ---
+
+  - `mutedForeground`
+  - `Color`
+
+  The color used for secondary text.
+
+  ---
+
+  - `primaryForeground`
+  - `Color`
+
+  The color used for text on the primary background.
+
+  ---
+
+  - `inputForeground`
+  - `Color`
+
+  The color used for text in input fields.
+
+  ---
+
+  - `neutral`
+  - `Color`
+
+  The color that will be used to generate the neutral shades the views use.
+
+  ---
+
+  - `ring`
+  - `Color`
+
+  The color of the ring when an interactive element is focused.
+
+  ---
+
+  - `muted`
+  - `Color`
+
+  The color used for muted backgrounds.
+
+  ---
+
+  - `shadow`
+  - `Color`
+
+  The base shadow color used in the views.
+
+  ---
+
+  - `border`
+  - `Color`
+
+  The base border color used in the views.
+</Properties>
+
+## Fonts
+
+The `typography` property contains the following font options based on iOS Dynamic Type:
+
+<Properties>
+  - `displaySmall`
+  - `TextStyle`
+
+  ---
+
+  - `headlineLarge`
+  - `TextStyle`
+
+  ---
+
+  - `headlineMedium`
+  - `TextStyle`
+
+  ---
+
+  - `titleMedium`
+  - `TextStyle`
+
+  ---
+
+  - `titleSmall`
+  - `TextStyle`
+
+  ---
+
+  - `bodyLarge`
+  - `TextStyle`
+
+  ---
+
+  - `bodyMedium`
+  - `TextStyle`
+
+  ---
+
+  - `bodySmall`
+  - `TextStyle`
+
+  ---
+
+  - `labelMedium`
+  - `TextStyle`
+
+  ---
+
+  - `labelSmall`
+  - `TextStyle`
+</Properties>
+
+## Design
+
+The `design` property contains the following design options:
+
+<Properties>
+  - `borderRadius`
+  - `Dp`
+
+  The border radius used throughout the views. By default, this is set to `8.0`.
+</Properties>
+
+## Usage
+
+You can customize Clerk Android views by creating a `ClerkTheme` and applying it to Clerk's `customTheme` setter.
+
+### Apply a custom theme to all Clerk views
+
+To customize all Clerk views in your app, create a `ClerkTheme` and apply it where you initialize the Clerk SDK.
+
+```kotlin
+import android.app.Application
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.unit.dp
+import com.clerk.api.Clerk
+import com.clerk.api.ui.ClerkColors
+import com.clerk.api.ui.ClerkDesign
+import com.clerk.api.ui.ClerkTheme
+
+class WorkbenchApplication : Application() {
+
+  override fun onCreate() {
+    super.onCreate()
+    val theme = ClerkTheme(
+        colors = ClerkColors(primary = Color.Black), 
+        design = ClerkDesign(borderRadius = 24.dp), 
+        typography = ClerkTypographyDefaults.displaySmall.copy(fontSize = 24.sp)
+    )
+
+    Clerk.initialize(this, "YOUR_PUBLIC_KEY", theme = theme)
+  }
+}
+
+```
+
+### Apply a theme to specific views
+
+You can apply a theme to specific Clerk views by passing a `ClerkTheme` to any Clerk UI component. The theme used here will apply to all children of this view.
+
+```kotlin
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.Alignment
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.background
+import com.clerk.api.Clerk
+import com.clerk.api.ui.ClerkColors
+import com.clerk.api.ui.ClerkDesign
+import com.clerk.api.ui.ClerkTheme
+import com.clerk.api.ui.ClerkTypographyDefaults
+import com.clerk.api.ui.UserButton
+import com.clerk.api.ui.AuthView
+
+@Composable
+fun HomeScreen {
+   val user by Clerk.userFlow.collecAsStateWithLifecycle()
+   Box(
+    modifier = Modifier.fillMaxSize().background(color = Color(0xFFF9F9F9)),
+    contentAlignment = Alignment.Center,
+   ) {
+        if (user != null) {
+            UserButton()
+        } else {
+            AuthView(clerkTheme = ClerkTheme(colors = ClerkColors(primary = Color.Blue)))
+        }
+    }
+}
+```
+
+### Custom fonts
+
+You can customize fonts by modifying the `typography` property of the `ClerkTheme`.
+
+#### Using a font family name
+
+```kotlin
+AuthView(clerkTheme = ClerkTheme(typography = ClerkTypography(displaySmall = ClerkTypographyDefaults.displaySmall.copy(fontSize = 24.sp))))
+```
+
+## Light and Dark Mode Support
+
+Clerk Android views automatically support both light and dark mode appearance, adapting seamlessly to the user's system preferences.
+
+{/* Add light and dark mode images */}
+
+If Clerk's prebuilt theming doesn't meet your specific needs, you can create completely custom authentication flows using the Clerk API. For more information, see the [custom flow guides](/docs/guides/development/custom-flows/overview).

docs/reference/components/overview.mdx

@@ -1,7 +1,7 @@
 ---
 title: Component Reference
 description: A list of Clerk's comprehensive suite of components designed to seamlessly integrate authentication and multi-tenancy into your application.
-sdk: react, nextjs, js-frontend, chrome-extension, expo, android, expressjs, fastify, react-router, remix, tanstack-react-start, go, astro, nuxt, vue, ruby, js-backend
+sdk: react, nextjs, js-frontend, chrome-extension, expo, expressjs, fastify, react-router, remix, tanstack-react-start, go, astro, nuxt, vue, ruby, js-backend
 ---
 
 Clerk offers a comprehensive suite of components designed to seamlessly integrate authentication and multi-tenancy into your application. With Clerk components, you can easily customize the appearance of authentication components and pages, manage the entire authentication flow to suit your specific needs, and even build robust SaaS applications.

docs/reference/views/authentication/auth-view.android.mdx

@@ -0,0 +1,50 @@
+---
+title: '`AuthView`'
+description: Clerk's AuthView renders a UI for signing in and signing up users on Android.
+sdk: android
+---
+
+![The AuthView renders a comprehensive authentication interface that handles both user sign-in and sign-up flows.](/docs/images/ui-components/android-auth-view.png){{ style: { maxWidth: '460px' } }}
+
+The `AuthView` renders a comprehensive authentication interface with support for multiple sign-up flows and sign-in methods, multi-factor authentication, password reset, and account recovery. The functionality of the `AuthView` is controlled by the instance settings you specify in the [Clerk Dashboard](https://dashboard.clerk.com), such as [sign-in and sign-up options](/docs/guides/configure/auth-strategies/sign-up-sign-in-options) and [social connections](/docs/guides/configure/auth-strategies/social-connections/all-providers).
+By default, the `AuthView` will automatically determine whether to sign users in or sign them up based on whether they already have an account. This is the default mode that provides seamless authentication without requiring users to choose between sign-in and sign-up.
+
+## Parameters
+
+<Properties>
+  - `modifier`
+
+  - `Modifier`
+
+  - A modifier that gets applied to the `AuthView` composable. This is by default applied to the top level `NavDisplay` and shouldn't be used
+    to change the appearance of the `AuthView` itself.
+</Properties>
+
+## Usage
+
+The following examples show how to use the `AuthView` in your Android app.
+
+### Basic usage
+
+```kotlin
+
+import androidx.compose.runtime.Composable
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.clerk.api.Clerk
+
+@Composable
+fun HomeScreen {
+  val user by Clerk.userFlow.collecAsStateWithLifecycle()
+  Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+    if (user != null) {
+      UserButton()
+    } else {
+      AuthView()
+    }
+  }
+}
+```
+
+## Customization
+
+<Include src="_partials/android/customization" />

docs/reference/views/overview.android.mdx

@@ -0,0 +1,48 @@
+---
+title: View Reference
+description: A list of Clerk's comprehensive suite of views designed to seamlessly integrate authentication into your application.
+sdk: android
+---
+
+Clerk offers a comprehensive suite of views designed to seamlessly integrate authentication into your application. With Clerk views, you can easily customize the appearance of authentication views and pages, manage the entire authentication flow to suit your specific needs, and even build robust SaaS applications.
+
+## Clerk Android views
+
+- [`AuthView`](/docs/reference/views/authentication/auth-view) - Renders a full authentication interface, supporting multiple sign-up and sign-in methods, multi-factor authentication (MFA), and password recovery flows.
+- [`UserButton`](/docs/reference/views/user/user-button) - Displays the signed-in user's profile image.
+- [`UserProfileView`](/docs/reference/views/user/user-profile-view) - Renders a complete user profile interface with personal information, security settings, account switching, and sign-out options.
+
+## Installation
+
+The Clerk Android SDK is now split into two packages:
+
+- `com.clerk:clerk-api` - The core Clerk SDK for authentication and user management.
+- `com.clerk:clerk-ui` - The Clerk UI components for authentication and user management.
+
+The `com.clerk:clerk-ui` pulls the `com.clerk:clerk-api` package as a dependency, so you only need to add the `com.clerk:clerk-ui` package to your dependencies if you're using the Clerk UI components.
+
+```gradle
+dependencies {
+    // Only if you're using the Clerk API without the Clerk UI components
+    implementation("com.clerk:clerk-api:<latest-version>")
+
+    implementation("com.clerk:clerk-ui:<latest-version>")
+}
+```
+
+You can find the latest version of the Clerk Android SDK on the [GitHub release page](https://github.com/clerk/clerk-android/releases).
+
+## Customization
+
+<Include src="_partials/android/customization" />
+
+### Secured by Clerk branding
+
+<Include src="_partials/feature-not-free-callout" />
+
+By default, Clerk displays a **Secured by Clerk** badge on Clerk views. You can remove this branding by following these steps:
+
+1. In the Clerk Dashboard, navigate to your application's [**Settings**](https://dashboard.clerk.com/~/settings).
+1. Under **Branding**, toggle on the **Remove "Secured by Clerk" branding** option.
+
+<Include src="_partials/help" />