{"id":"8955f5b9-b4b4-45e4-b2fe-1ab9dbda5595","shortId":"YgNX4g","kind":"skill","title":"cometchat-theming","tagline":"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.","description":"> **Companion skills:** `cometchat-core` covers CSS import placement\n> and the one-import rule; `cometchat-customization` covers\n> component-level CSS selectors for deeper overrides;\n> `cometchat-troubleshooting` handles cases where the theme doesn't\n> apply.\n\n## Purpose\n\nTeach Claude how to theme CometChat in a v3 (AI-written) integration.\nThemes are just CSS variable overrides — you write them directly into\nthe project's CSS (or, for Astro, the React island file). **Do not use\nthe `cometchat apply-theme` CLI command — it was a v2 tool that expects\na CLI-generated `.cometchat/state.json` marker that v3 integrations\ndon't create, and it will fail with \"No integration found\".**\n\n---\n\n## 1. How CometChat theming works\n\n### The CSS variable cascade\n\nCometChat's entire visual identity is driven by **200+ CSS custom\nproperties** defined in `@cometchat/chat-uikit-react/css-variables.css`.\nThis file is imported once at the app root (see `cometchat-core`).\nEvery `` component reads these variables — there is no\ncomponent-level style-props API for colors, fonts, or spacing.\n\nTo override: write CSS rules that set `--cometchat-*` variables on\n`:root` (or a scoped container), **after** the `css-variables.css`\nimport. The cascade does the rest — every component picks up the new\nvalues automatically.\n\n```css\n/* Must appear AFTER the @import of css-variables.css */\n:root {\n --cometchat-primary-color: #6C63FF;\n --cometchat-background-color-01: #FFFFFF;\n --cometchat-text-color-primary: #141414;\n --cometchat-font-family: \"Inter\", sans-serif;\n --cometchat-radius-2: 8px;\n}\n```\n\n### Dark mode\n\nTwo broad strategies — pick based on how the project already handles dark mode.\n\n**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:\n\n```css\n@media (prefers-color-scheme: dark) {\n :root {\n --cometchat-primary-color: #7B73FF;\n --cometchat-background-color-01: #1A1A2E;\n --cometchat-text-color-primary: #E0E0E0;\n /* ... remaining dark overrides ... */\n }\n}\n```\n\n**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:\n\n```css\n/* next-themes default: applies a `.dark` class to */\n.dark :root {\n --cometchat-primary-color: #7B73FF;\n --cometchat-background-color-01: #1A1A2E;\n --cometchat-text-color-primary: #E0E0E0;\n}\n\n/* OR if the project uses data-theme=\"dark\" on (common with Tailwind CSS v4) */\n[data-theme=\"dark\"] :root {\n --cometchat-primary-color: #7B73FF;\n --cometchat-background-color-01: #1A1A2E;\n --cometchat-text-color-primary: #E0E0E0;\n}\n\n/* OR for Tailwind's `class` strategy with `darkMode: 'class'` in tailwind.config */\nhtml.dark {\n --cometchat-primary-color: #7B73FF;\n --cometchat-background-color-01: #1A1A2E;\n --cometchat-text-color-primary: #E0E0E0;\n}\n```\n\n**How to tell which selector the project uses:**\n\n| Library / setup | Selector to target |\n|---|---|\n| `next-themes` (Next.js default) | `.dark` on `` |\n| Tailwind with `darkMode: 'class'` | `html.dark` (or `.dark` on any ancestor) |\n| Tailwind with `darkMode: 'media'` | Matches `@media (prefers-color-scheme: dark)` — use Strategy A |\n| Tailwind CSS v4 (`@custom-variant dark`) | `[data-theme=\"dark\"]` by default |\n| Radix UI / shadcn defaults | `.dark` class on `` |\n| Custom React Context (`useTheme()` hook) | Check what the context writes to the DOM — usually a class on `` or `` |\n\n**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.\n\n**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.\n\n### Why Astro is different\n\nAstro's `client:only=\"react\"` islands run in isolation — global\nstylesheets in `.astro` layouts do not cascade into them. CSS variable\noverrides in a global `.css` file will have no effect on CometChat\ncomponents. The overrides must live **inside the React island `.tsx`\nfile** (typically `src/cometchat/ChatApp.tsx`), as an inline `