--- name: cometchat-theming description: Customize CometChat UI to match the user's app design system. Covers the CSS variable cascade, preset themes, brand color overrides, design system extraction, dark mode, and framework-specific override locations. license: "MIT" compatibility: "Node.js >=18; @cometchat/chat-uikit-react ^6; integration must already be applied" metadata: author: "CometChat" version: "3.1.0" tags: "cometchat theming css customization branding dark-mode" --- > **Ground truth:** per-platform UI Kit theme system + `docs/ui-kit`. **Official docs:** https://www.cometchat.com/docs/ui-kit/react/theme · **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-core` covers CSS import placement > and the one-import rule; `cometchat-customization` covers > component-level CSS selectors for deeper overrides; > `cometchat-troubleshooting` handles cases where the theme doesn't > apply. ## Purpose Teach Claude how to theme CometChat in a v3 (AI-written) integration. Themes are just CSS variable overrides — you write them directly into the project's CSS (or, for Astro, the React island file). **Do not use the `cometchat apply-theme` CLI command — it was a v2 tool that expects a CLI-generated `.cometchat/state.json` marker that v3 integrations don't create, and it will fail with "No integration found".** --- ## 1. How CometChat theming works ### The CSS variable cascade CometChat's entire visual identity is driven by **200+ CSS custom properties** defined in `@cometchat/chat-uikit-react/css-variables.css`. This file is imported once at the app root (see `cometchat-core`). Every `` component reads these variables — there is no component-level style-props API for colors, fonts, or spacing. **Scope to `.cometchat`, not `:root`.** The UI Kit renders under a `.cometchat` root element. The canonical scope (per the docs) is that class — it keeps the overrides from leaking into the rest of your app, and it's where component-scoped overrides hang off. (`:root` *works* because CSS variables inherit downward, but it's global and lower-precedence — prefer `.cometchat`.) Write the rules **after** the `css-variables.css` import. ```css /* Must appear AFTER the @import of css-variables.css */ /* Global — applies to every CometChat component */ .cometchat { --cometchat-primary-color: #6C63FF; --cometchat-background-color-01: #FFFFFF; --cometchat-text-color-primary: #141414; --cometchat-font-family: "Inter", sans-serif; --cometchat-radius-2: 8px; } /* Component-scoped — only the conversations list */ .cometchat .cometchat-conversations { --cometchat-primary-color: #FF6C63; } ``` **Precedence ladder** (highest wins): runtime `element.style.setProperty(...)` → component-scoped `.cometchat .cometchat- { --var }` → global `.cometchat { --var }` → the kit's `css-variables.css` defaults. ### Dark mode Two broad strategies — pick based on how the project already handles dark mode. **Strategy A — OS-driven only** (simplest). Overrides live inside a `@media (prefers-color-scheme: dark)` block. The browser swaps themes based on the user's OS preference: ```css @media (prefers-color-scheme: dark) { .cometchat { --cometchat-primary-color: #7B73FF; --cometchat-background-color-01: #1A1A2E; --cometchat-text-color-primary: #E0E0E0; /* ... remaining dark overrides ... */ } } ``` **Strategy B — App-controlled theme toggle.** If the project already has a theme toggle (next-themes, Tailwind `dark:` prefix, React Context, etc.), wire CometChat's dark mode to the same trigger. The trigger is typically a class or `data-theme` attribute on an ancestor (``/``/the `.cometchat-root` wrapper). Scope the override to **`.cometchat` under that ancestor** — NOT `:root` (a bare `:root` can never be a *descendant* of `.dark`/`[data-theme]`, so `.dark :root { }` matches nothing): ```css /* next-themes default: applies a `.dark` class to */ .dark .cometchat { --cometchat-primary-color: #7B73FF; --cometchat-background-color-01: #1A1A2E; --cometchat-text-color-primary: #E0E0E0; } /* OR data-theme="dark" on the wrapper (the kit's own convention + Tailwind v4) */ .cometchat-root[data-theme="dark"] .cometchat { --cometchat-primary-color: #7B73FF; --cometchat-background-color-01: #1A1A2E; --cometchat-text-color-primary: #E0E0E0; } /* OR for Tailwind's `class` strategy with `darkMode: 'class'` in tailwind.config */ html.dark .cometchat { --cometchat-primary-color: #7B73FF; --cometchat-background-color-01: #1A1A2E; --cometchat-text-color-primary: #E0E0E0; } ``` **How to tell which selector the project uses:** | Library / setup | Selector to target | |---|---| | `next-themes` (Next.js default) | `.dark` on `` | | Tailwind with `darkMode: 'class'` | `html.dark` (or `.dark` on any ancestor) | | Tailwind with `darkMode: 'media'` | Matches `@media (prefers-color-scheme: dark)` — use Strategy A | | Tailwind CSS v4 (`@custom-variant dark`) | `[data-theme="dark"]` by default | | Radix UI / shadcn defaults | `.dark` class on `` | | Custom React Context (`useTheme()` hook) | Check what the context writes to the DOM — usually a class on `` or `` | **Rule:** whichever selector is toggled by the app's theme system, use that same selector as the CometChat override's parent. The UI Kit components sit inside the app's DOM, so they inherit whatever variable values are active at the nearest matching scope. **Do not** emit both Strategy A and Strategy B in the same stylesheet unless the user explicitly wants "follow OS except when app toggle is set." That's a legitimate pattern but usually over-engineered for a first integration — ship Strategy B alone if the project has a toggle, Strategy A if it doesn't. ### Why Astro is different Astro's `client:only="react"` islands run in isolation — global stylesheets in `.astro` layouts do not cascade into them. CSS variable overrides in a global `.css` file will have no effect on CometChat components. The overrides must live **inside the React island `.tsx` file** (typically `src/cometchat/ChatApp.tsx`), as an inline `