[raj-dubey1]

Adds a single, cross-platform experience blueprint / design system that any AI coding agent can follow to build production-grade, WhatsApp/Telegram/iMessage/Slack/Discord-class chat UIs end-to-end, on the customer's own brand. No skill changes in this PR: skills 5.1 don't reference it yet; the unreleased 5.2.0 reads it in clone mode.

Placement

Added to the AI-Driven Development tab next to Lovable (one docs.json line). That tab is hidden from the nav, so the page is reached by link (/docs/design-system, linked from Agent Skills) rather than browsing.

Platform-generic

Applies to every UI Kit and SDK — React, Angular, Vue, React Native, iOS, Android, Flutter (and headless Chat/Calls SDKs). Component names are consistent across families; exact props/theme keys are fetched from each family's docs.

What's in design-system.mdx

• Before you start (prerequisites) — app + credentials, target family, archetype/scope, brand assets, fresh-vs-retrofit, docs access.
• How an agent must use it + grounding rules (APIs from docs, theme through the kit, brand is the customer's, non-breaking retrofit).
• UX principles — the "feels real" bar (optimistic send, receipts, typing, grouping, date separators, unread divider, smooth scroll, media/voice notes, reactions, replies, threads, mentions, search, empty/loading/error/offline, push, a11y/i18n).
• Design tokens — semantic color roles (light + dark), typography, spacing/radius/elevation/density — mapped to each family's theming API.
• Motion & animation — per-interaction durations/easing, prefers-reduced-motion aware, native transitions on mobile.
• Layout & responsiveness — mobile 1-pane / tablet 2-pane / desktop 3-pane + details drawer.
• Component map — the real UI Kit components → app regions; headless SDK for fully custom.
• App archetypes (WhatsApp / Telegram / iMessage / Slack / Discord / support / community / marketplace), a full-feature checklist, fresh-build + non-breaking retrofit playbooks, and an acceptance checklist.
• Brand ownership + Where to get exact APIs.

Safety

• Additive: one new page + one nav line. Nothing moved/renamed/deleted → no 404/redirect/build risk.
• docs.json valid; all internal links resolve; no MDX components (clean .md twin for agents).

Shareable URL after merge: https://www.cometchat.com/docs/design-system (and …/design-system.md for the agent-read twin).

🤖 Generated with Claude Code

https://claude.ai/code/session_01PT9pMg3MSZEW3gsb6jPc3E

Update: cloning any app, kit vs your own UI, design sync

• Cloning an existing app (research every detail): for any app the user names, the agent inventories every screen and feature: entry point → container (dialog, popover, side panel, page) → close, rows, messages, composer, shortcuts, states, copy, measured visual tokens, motion and responsive behavior. Details it can't confirm are marked unverified and asked, never filled with kit defaults.
• Kit component or your own UI (decide per item): build levels L0–L6, from kit as-is, through config, slots and kit in your own container, to your own UI on the SDK, third-party, and not possible. Placement differences are solved by hosting the kit component (e.g. search in a centered dialog), not by accepting the kit's default layout or rebuilding.
• Design sync: one token source measured from the target; kit components and custom UI both use it; side-by-side screenshot comparison until no unagreed difference remains.
• Requirements table gains target behavior and build level columns; every archetype gets interaction patterns; navigation, premium look, the search gotcha, build/retrofit steps and the verify checklist now follow the target. Still brand-neutral.
• Rebased onto main (docs.json conflict resolved alongside migrate-with-agent-skills and lovable).

Review fixes (9ca0b7e)

Merged main (the branch was 283 commits behind) and fixed the review findings:

• Header search: React's CometChatMessageHeader has a search button (showSearchOption, on by default). The page now says to use it or hide it, so the header doesn't show two. Other kits' headers have none.
• Auth-token login per kit: loginWithAuthToken(token) on React, Angular, Android and Flutter; login(authToken:) on iOS; login({ authToken }) on React Native.
• Skills wording: Agent Skills says an agent can follow the blueprint (skills 5.1 don't reference it).
• Cascade: React v7 tokens are in @layer cometchat, so unlayered overrides already win; layered CSS needs the layer order. The doubled-class advice now applies to Angular, whose CSS isn't layered.
• Flutter uses CometChatLocalize plus Translations.delegate; the React Native example lists the kit's real peers (no Reanimated).

mint broken-links: no errors in the changed pages (ui-kit/react/integration-astro.mdx fails to parse on main already).

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cometchat	🟢 Ready	View Preview	Nov 13, 2026, 11:00 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[jitvarpatil]

Requesting changes on three statements an agent would copy straight into a customer app. The build is safe: after merging with main, docs.json gains only the one nav line, and every nav ref resolves.

1. design-system.mdx:942 says there is no built-in search on CometChatMessageHeader. React 7.2.6 has showSearchOption (default true) and onSearchOptionClicked, and ui-kit/react/components/message-header.mdx documents both. An agent following this adds a second search button.
2. design-system.mdx:442 gives loginWithAuthToken(token) for every kit. iOS is CometChatUIKit.login(authToken:result:) and React Native is CometChatUIKit.login({ authToken }). Name the call per platform.
3. agent-skills.mdx:135 and :366 say the skills follow this blueprint. @cometchat/skills 5.1.0 never references /design-system; its own contract says to reuse the app's existing design system. Either ship a skills release that points here, or say agents can follow it.

Smaller:

• :1020–1022 says Flutter uses delegates and Translations. Flutter 6.3.0 also ships CometChatLocalize (ui-kit/flutter/localize.mdx).
• :1031 gives the Reanimated / worklets Babel plugin as the React Native example. The RN kit (5.5.4) doesn't use Reanimated.
• :622–626: React v7 declares its tokens inside @layer cometchat, so any unlayered customer rule already wins, and extra specificity won't beat it if the customer's own CSS is layered. The .cometchat.cometchat advice is harmless; the reason given is wrong.
• The description says the page is listed in Developer Tools; docs.json adds it to the hidden AI-Driven Development tab. The branch is 283 commits behind main, so the preview is built from an old tree.

[jitvarpatil]

🤖 Review Buddy (review-docs-pr)

Recommendation: approve. Automated review; the final decision stays with a maintainer.

TL;DR: This PR only adds things: one new page (design-system.mdx, 1,135 lines), one new section and a card in agent-skills.mdx, and one nav entry in the hidden AI-Driven Development tab. Nothing is moved, renamed or deleted, so no redirects are needed and nothing will 404. The nav entry resolves, docs.json is valid JSON, and every internal link and all 25 in-page anchors resolve. I checked the page's specific API claims against the current kit source, and they hold. No P0 or P1 findings. Four P2 nits are listed below. Note: the PR still carries the do not merge label, so the author or a maintainer needs to remove it before merging.

P0: none

P1: none

P2 / nits

1. The front-matter description doesn't match the PR's own fix. design-system.mdx:4 says this is the design system "CometChat's AI skills (and any AI coding agent) follow". The last commit changed agent-skills.mdx to say an agent can follow it, because skills 5.1 don't reference it yet. Suggest "…that an AI coding agent can follow…". The description is also about 480 characters long. Search snippets and link unfurls cut off around 160, so consider trimming it.
2. The numbered steps read as part of the one-line flow. design-system.mdx:96-130: the 1–10 list ("Run discovery first…" through "Verify") comes right after "One approval, then build", still under the ### From a one-line request heading. It is really the general procedure. Give it its own heading (for example ### The process) so an agent doesn't think it applies only to short requests.
3. A version-pinned selector list will drift. design-system.mdx:929 lists composer selectors for "React UI Kit v7.2". They match dev-v7 today (CometChatMessageComposer.css, hue-rotate(235deg) at :805; __ai-button:hover at :1194). Add a one-line "re-check these against the installed kit version" so a future CSS rename doesn't send agents to dead selectors.
4. A vague hedge. design-system.mdx:1032: "check the version's docs — this has been changing" for Flutter localization. Link to /ui-kit/flutter/localize inline (it's already in "Where to get exact APIs") or drop the hedge.

Checked and passed

• Redirects: 0 removed or renamed files, so no redirects are needed and no existing redirects are broken.
• Navigation: design-system was added to AI-Driven Development (hidden: true) and resolves to design-system.mdx. docs.json parses.
• Links: all 17 internal page links resolve on the PR head (theming ×6, localization ×6, ui-kit/react/components/conversations, agent-skills, mcp-server, fundamentals/key-concepts, /design-system). All 25 #anchor links match heading slugs.
• API claims checked against source:
  • Auth-token login per kit: React, Angular and Flutter use loginWithAuthToken; iOS uses login(authToken:); React Native uses login({ authToken }).
  • React @layer cometchat, --cometchat-message-list-bg, showSearchOption / onSearchOptionClicked, and CometChatThreadView.
  • Search returns HTTP 402 until Search is enabled on the plan, which matches ui-kit/react/components/search.mdx.
  • Android CometChatTheme.DayNight and Flutter CometChatTheme.mergeThemeExtensions.
• Content: no TODO, FIXME or placeholder leftovers, no images to resolve, and no competitor brand names left in prose or example prompts (they now use placeholders).

Skipped

• mint broken-links / mint dev build: not run here. The checks above cover what it would catch for this additive change. The PR body reports mint broken-links clean on the changed pages.
• Rendered preview: not opened. The Mintlify preview deploy is 🟢 Ready.