cometchat-flutter-v5-theming

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

Ground truth: cometchat_chat_uikit: ^5.2 (legacy/maintenance-only; calls via raw cometchat_calls_sdk ^5.0.2) — pub-cache source + ui-kit/flutter/v5. Official docs: https://www.cometchat.com/docs/ui-kit/flutter/v5/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.

CometChat Flutter UIKit v5 — Theming & Styling

How to customize the visual appearance of all CometChat v5 components.

Theme System Architecture

Three layers, resolved via Flutter's ThemeExtension system:

1. CometChatColorPalette — colors (primary, neutral, alert, background, text, icon, button, border)
2. CometChatSpacing — spacing, padding, margin, and radius tokens
3. CometChatTypography — text styles (heading1-4, body, caption1-2, button, link, title)

Access via static helpers:

final colors = CometChatThemeHelper.getColorPalette(context);
final spacing = CometChatThemeHelper.getSpacing(context);
final typography = CometChatThemeHelper.getTypography(context);

Important: getColorPalette() creates a new object every call, resolving each token via Theme.of(context). Cache in didChangeDependencies(), never call in build().

Applying a Custom Theme

Register CometChatColorPalette as a ThemeExtension on your ThemeData:

// ✅ CORRECT
MaterialApp(
  theme: ThemeData(
    extensions: [
      CometChatColorPalette(
        primary: const Color(0xFF6852D6),
        textPrimary: const Color(0xFF141414),
        textSecondary: const Color(0xFF727272),
      ),
    ],
  ),
  darkTheme: ThemeData(
    extensions: [
      CometChatColorPalette(
        primary: const Color(0xFF604CC3),
        textPrimary: const Color(0xFFFFFFFF),
        textSecondary: const Color(0xFFA0A0A0),
      ),
    ],
  ),
)

Dark Mode

CometChatThemeMode.mode = ThemeMode.dark;   // Force dark
CometChatThemeMode.mode = ThemeMode.system;  // Follow system

Commonly Used Color Tokens

Extended primary shades (extendedPrimary50–900) are auto-generated from primary. Override individually if needed.

Commonly Used Spacing Tokens

Typography Tokens

CometChatTypography provides: heading1–heading4, body, caption1, caption2, button, link, title.

Each has .bold, .medium, .regular variants:

typography.body?.regular?.fontSize
typography.heading2?.bold?.fontWeight
typography.caption1?.regular?.fontFamily

Theme Caching Pattern (from package source)

All UIKit components cache theme unconditionally in didChangeDependencies():

// ✅ CORRECT — matches actual package pattern
@override
void didChangeDependencies() {
  super.didChangeDependencies();
  colorPalette = CometChatThemeHelper.getColorPalette(context);
  spacing = CometChatThemeHelper.getSpacing(context);
  typography = CometChatThemeHelper.getTypography(context);
}

Do NOT use a _themeInitialized flag — it prevents theme updates on system theme changes.

Component Style Classes — merge() Pattern

Every component has a CometChat{Component}Style extending ThemeExtension. Resolved internally:

// Inside component's didChangeDependencies():
style = CometChatThemeHelper.getTheme<CometChatConversationsStyle>(
    context: context,
    defaultTheme: CometChatConversationsStyle.of,
).merge(widget.conversationsStyle);

Pass overrides via constructor:

CometChatConversations(
  conversationsStyle: CometChatConversationsStyle(
    backgroundColor: Colors.black,
  ),
)

Gotchas

• colorPalette.white / black / transparent are NOT brightness-aware — use neutral50 for brightness-aware white
• Extended primary shades auto-generated from primary by blending with white (light) or black (dark)

Checklist — Theming

• Colors from CometChatThemeHelper.getColorPalette(context), never hardcoded
• Theme cached in didChangeDependencies(), not build()
• Custom theme registered as ThemeExtension on both theme and darkTheme
• Component styles passed via constructor props