--- 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" allowed-tools: "executeBash, readFile, fileSearch, listDirectory, grepSearch" metadata: author: "CometChat" version: "3.1.0" tags: "cometchat theming css customization branding dark-mode" --- > **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. To override: write CSS rules that set `--cometchat-*` variables on `:root` (or a scoped container), **after** the `css-variables.css` import. The cascade does the rest — every component picks up the new values automatically. ```css /* Must appear AFTER the @import of css-variables.css */ :root { --cometchat-primary-color: #6C63FF; --cometchat-background-color-01: #FFFFFF; --cometchat-text-color-primary: #141414; --cometchat-font-family: "Inter", sans-serif; --cometchat-radius-2: 8px; } ``` ### 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) { :root { --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 shared trigger is typically a CSS class or `data-theme` attribute on `` or ``. Scope the override to that selector: ```css /* next-themes default: applies a `.dark` class to */ .dark :root { --cometchat-primary-color: #7B73FF; --cometchat-background-color-01: #1A1A2E; --cometchat-text-color-primary: #E0E0E0; } /* OR if the project uses data-theme="dark" on (common with Tailwind CSS v4) */ [data-theme="dark"] :root { --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-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 `