cometchat-android-v6-kotlin-theming

Imported from cometchat/cometchat-skills (skills/cometchat-android-v6-kotlin-theming/SKILL.md). Install upstream with npx skills add cometchat/cometchat-skills --skill cometchat-android-v6-kotlin-theming. Copyright stays with the author (MIT).

Ground truth: com.cometchat:chatuikit-{compose,kotlin}-android:6.x (+ calls-sdk-android:5.x) — resolved AAR (javap) + ui-kit/android/v6. Official docs: https://www.cometchat.com/docs/ui-kit/android/v6/overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.

Companion skills: cometchat-android-v6-compose-theming (Compose equivalent), cometchat-android-v6-kotlin-components, cometchat-android-v6-kotlin-customization

Purpose

Apply and customize the CometChat theme in Kotlin Views — XML theme attributes, programmatic color/font overrides via the CometChatTheme singleton, dark mode support, and per-component style classes.

Use this skill when

• Setting CometChat theme colors via XML attributes or programmatically
• Overriding primary, neutral, alert, or button colors
• Customizing typography and fonts
• Implementing dark mode for Kotlin Views components
• Clearing the theme cache after dynamic theme changes

Do not use this skill when

• Working with Compose theming (use cometchat-android-v6-compose-theming)
• Customizing bubble rendering (use cometchat-android-v6-kotlin-customization)

1. CometChatTheme Singleton

CometChatTheme is a Kotlin object in com.cometchat.uikit.kotlin.theme that provides Context-based getters and setters for all theme tokens.

import com.cometchat.uikit.kotlin.theme.CometChatTheme

// Get a color (requires Context)
val primaryColor: Int = CometChatTheme.getPrimaryColor(context)
val textColor: Int = CometChatTheme.getTextColorPrimary(context)

// Set a color programmatically (cached globally)
CometChatTheme.setPrimaryColor(Color.parseColor("#6851D6"))
CometChatTheme.setErrorColor(Color.RED)

2. XML Theme Attributes

The app/activity theme MUST extend CometChatTheme.DayNight (required — components crash without it). The kit ships CometChatTheme.DayNight (parent Theme.MaterialComponents.DayNight.NoActionBar), which defines every cometchat* theme attribute the component layouts reference. Parenting a plain Theme.MaterialComponents / Theme.Material3 / Theme.AppCompat instead leaves those attrs unresolved and the first component inflate crashes — e.g. CometChatConversations (which inflates a MaterialButton/MaterialCardView) throws java.lang.UnsupportedOperationException: Failed to resolve attribute … or IllegalArgumentException: requires your app theme to be Theme.MaterialComponents. Set it in AndroidManifest.xml via android:theme="@style/AppTheme" (or android:theme="@style/CometChatTheme.DayNight" directly). Verified by building + running on-device, 2026-06-11.

Define theme colors in your app's styles.xml or themes.xml, parenting the kit theme:

<!-- parent MUST be CometChatTheme.DayNight (or a descendant) -->
<style name="AppTheme" parent="CometChatTheme.DayNight">
    <!-- Override only what you want; the parent supplies all defaults. -->
    <!-- Primary -->
    <item name="cometchatPrimaryColor">#6851D6</item>

    <!-- Neutral scale -->
    <item name="cometchatNeutralColor50">#FAFAFA</item>
    <item name="cometchatNeutralColor100">#F5F5F5</item>
    <item name="cometchatNeutralColor200">#E8E8E8</item>
    <!-- ... through cometchatNeutralColor900 -->

    <!-- Alert colors -->
    <item name="cometchatSuccessColor">#34C759</item>
    <item name="cometchatErrorColor">#FF3B30</item>
    <item name="cometchatWarningColor">#FFCC00</item>
    <item name="cometchatInfoColor">#007AFF</item>
    <item name="cometchatMessageReadColor">#007AFF</item>

    <!-- Background colors -->
    <item name="cometchatBackgroundColor1">@color/bg1</item>
    <!-- ... through cometchatBackgroundColor4 -->

    <!-- Stroke/border colors -->
    <item name="cometchatStrokeColorDefault">@color/stroke</item>
    <item name="cometchatStrokeColorLight">@color/strokeLight</item>
    <item name="cometchatStrokeColorDark">@color/strokeDark</item>
    <item name="cometchatStrokeColorHighlight">@color/primary</item>

    <!-- Text colors -->
    <item name="cometchatTextColorPrimary">@color/textPrimary</item>
    <item name="cometchatTextColorSecondary">@color/textSecondary</item>
    <!-- ... -->

    <!-- Icon tints -->
    <item name="cometchatIconTintPrimary">@color/iconPrimary</item>
    <!-- ... -->

    <!-- Button colors -->
    <item name="cometchatPrimaryButtonBackgroundColor">@color/primary</item>
    <item name="cometchatPrimaryButtonIconTint">@color/white</item>
    <item name="cometchatPrimaryButtonTextColor">@color/white</item>
    <!-- ... -->
</style>

3. Color Token Reference

3.1 Primary Colors

3.2 Extended Primary (auto-generated from primary)

Extended primary colors auto-generate by blending primary with white (day) or black (night) if not explicitly set.

3.3 Neutral Colors

getNeutralColor50(ctx) through getNeutralColor900(ctx) with corresponding setters and XML attrs cometchatNeutralColor50 through cometchatNeutralColor900.

3.4 Alert Colors

3.5 Background, Stroke, Text, Icon, Button Colors

All follow the same pattern: get{Token}(ctx) / set{Token}(color) / cometchat{Token} XML attr. Defaults fall back to neutral scale values if not explicitly set.

Border color aliases: getBorderColorLight() = getStrokeColorLight(), getBorderColorDefault() = getStrokeColorDefault(), getBorderColorDark() = getStrokeColorDark(). Note: StrokeColor also has a Highlight variant (getStrokeColorHighlight()); there is no getBorderColorHighlight().

4. Typography

// Get text appearance resource IDs
val titleBold: Int = CometChatTheme.getTextAppearanceTitleBold(context)
val bodyRegular: Int = CometChatTheme.getTextAppearanceBodyRegular(context)
val heading1Medium: Int = CometChatTheme.getTextAppearanceHeading1Medium(context)
// ... combinations: Title, Heading1-4, Body, Caption1-2, Button each have Regular/Medium/Bold.
// Link is the exception — only getTextAppearanceLinkRegular(context) exists (no Medium/Bold).

// Get font resource IDs
val regularFont: Int = CometChatTheme.getFontRegular(context)
val mediumFont: Int = CometChatTheme.getFontMedium(context)
val boldFont: Int = CometChatTheme.getFontBold(context)

Override via XML attrs: cometchatTextAppearanceTitleBold, cometchatFontRegular, etc.

5. Dark Mode

Dark mode is detected via Configuration.UI_MODE_NIGHT_MASK:

val nightMode = context.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
val isDark = nightMode == Configuration.UI_MODE_NIGHT_YES

The theme automatically:

• Uses day/night qualified XML resources
• Blends extended primary colors with white (day) or black (night)
• Falls back to appropriate neutral scale for each mode

For programmatic overrides, set colors after detecting the mode:

if (isDark) {
    CometChatTheme.setPrimaryColor(Color.parseColor("#BB86FC"))
} else {
    CometChatTheme.setPrimaryColor(Color.parseColor("#6851D6"))
}

6. Theme Cache

Programmatic overrides are cached in memory. Clear the cache when the theme changes:

CometChatTheme.clearCache()

Call this when:

• The user switches between light and dark mode at runtime
• You dynamically change the primary color
• The Activity recreates with a new theme

7. Static Colors

val white: Int = CometChatTheme.getColorWhite(context)
val black: Int = CometChatTheme.getColorBlack(context)
val transparent: Int = CometChatTheme.getColorTransparent(context)

Localization

To translate the UI, switch the active language, or override individual strings, route to the dedicated cometchat-i18n skill — the canonical cross-family localization reference. Android uses CometChatLocalize.setLocale(context, Language.Code.<lang>) / getLocale(context) (a separate method, not an init object — unlike web/RN). cometchat-i18n covers bundled languages, custom translations, and RTL. Docs: https://www.cometchat.com/docs/ui-kit/android/localize

Sound Manager — custom notification & call sounds

Sounds are a behavioral customization — driven by CometChatSoundManager, an instance class that needs a Context. The UI Kit plays the built-in cues automatically; use this to override a cue with your own raw resource. V6 package (NOT the V5 com.cometchat.chatuikit.* path):

import com.cometchat.uikit.core.resources.soundmanager.CometChatSoundManager
import com.cometchat.uikit.core.resources.soundmanager.Sound

val soundManager = CometChatSoundManager(context)

// Play a default cue — Sound enum is SCREAMING_SNAKE_CASE: INCOMING_CALL |
//   OUTGOING_CALL | INCOMING_MESSAGE | INCOMING_MESSAGE_FROM_OTHER | OUTGOING_MESSAGE
soundManager.play(Sound.INCOMING_CALL)

// Override with your own raw resource (R.raw.*)
soundManager.play(Sound.INCOMING_MESSAGE, R.raw.my_ping)

// Stop whatever is playing
soundManager.pause()

Hard rules

• ALWAYS pass a valid Context to getter methods — they resolve XML attributes from the theme
• Call CometChatTheme.clearCache() after programmatic theme changes to ensure fresh values
• Programmatic setters (setPrimaryColor(), etc.) take priority over XML attributes
• Extended primary colors auto-generate from the primary color — only override them if you need specific shades
• Do NOT mix Compose CometChatTheme.colorScheme with Views CometChatTheme.getPrimaryColor(ctx) — they are separate theme systems in separate modules