> ## Documentation Index
> Fetch the complete documentation index at: https://watermelon.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Chat widget style guide
> A practical guide to designing a branded, accessible chat widget — your way
### Who this guide is for
Your chat widget represents your brand. This guide gives you guardrails, defaults, and decision frameworks to make intentional choices — without needing design support.
**You decide:**
* What fits your brand
* What matches your audience
* What feels right for your tone and use case
## **Quick style guide summary**
If you read nothing else, start here:
* Use **neutral backgrounds**
* Use **one brand color**, sparingly
* Pick **one avatar style** and stick to it
* Use **one corner radius system**
* Use **system or sans-serif fonts** for chat text
* Make the **launcher clearly invite interaction**
Everything below explains how to apply this.
## **Core design principles**
Decision output
* If your website is minimal → use neutral chat backgrounds
* If your website is bold → limit brand color to launcher and buttons
Decision output
* Use color to signal *action*, not decoration
* Remove any visual element that does not improve clarity or readability
Decision output
* Prioritize legibility over brand expression
* Avoid headline fonts, gradients, or dense layouts inside messages
Decision output
* One font family that matches your website
* One avatar style that matches your brand
* One corner radius system
* One color logic
If you need exceptions, simplify further.
## **Color usage: the Golden Ratio (widgets edition)**
**Recommended rule: 60–30–10**
Use color in roles, not freely.
* **60% Neutral**
Background of home and chat screen
* **30% Secondary**
Message bubbles
* **10% Primary (brand color)**
Launcher, buttons (home and send), header
This prevents “color bomb” widgets that feel loud or untrustworthy.
**Safe default (if unsure)**
* 80–90% neutral
* Brand color **only** for:
* Launcher
* Button and send button
**Avoid if**
* Your primary brand color is:
* Neon
* Very dark
* Very light
* Use a muted, adjusted, or darker/lighter variant instead.
## **Accessibility is not optional**
**Required standard**
* Text-to-background contrast ratio: **minimum 4.5:1**
* This will make sure that your chat widget and text within the widget are readable
**How to verify**
* [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
* [Adobe Color – Accessibility tools](https://color.adobe.com/nl/create/color-contrast-analyzer)
**Why this matters**
Poor contrast leads to:
* Users missing agent replies
* Higher abandonment rates
* Complaints that chat is “broken” (even when it works)
If users can’t read it, they won’t trust it.
## **Shape = brand “vibe”**
| **Style** | **Corner radius** | **Best for** |
| :------------ | :---------------- | :-------------------------- |
| Modern / Soft | 12–16px | SaaS, lifestyle, creative |
| Professional | 4–8px | Legal, finance, enterprise |
| Playful | 24px+ (pill) | Consumer apps, Gen-Z brands |
**Decision**
* Pick one row
* Apply it everywhere (bubbles, buttons, inputs)
Mixed shapes feel unpolished.
## **Choosing the right avatar**
Your avatar is the *face* of your AI agent.
### **Choose one strategy**
**Company logo**
* Best for: general help, support, knowledge agents
* Feels official and brand-first
**AI-generated or stylized human**
* Best for: sales, guided support
* Must match brand tone and expectations
**Illustrated mascot**
* Best for: approachable tech brands
* Humanizes AI without pretending it’s human
### **Avoid**
* Using a real employee photo for an AI agent
* Mixing logo + mascot across widget states
These create trust issues, am I talking to a human or an AI agent?
## **Typography: choose readability over branding**
### **Decision**
* Use **system or sans-serif fonts** for chat messages
* Keep marketing or display fonts out of conversations
**Why**
Chat is read in small, fast-scanning blocks. Decorative fonts reduce comprehension and make it harder to read.
## **The launcher**
The launcher is the first interaction users have with your widget.
### **Decision: icon vs eye-catcher**
* **Icon only** → subtle, familiar
* **Icon + eye-catcher** (e.g. “Help”, “Questions?”) → clearer intent, especially for first-time visitors
In our experience, adding a short eye-catcher often increases engagement, particularly for new visitors.
\
**Launcher color: how it should stand out**
**Recommended approach**
* Use **one strong, intentional color**
* In most cases, this is your **primary brand color**
* The launcher should be the **highest-contrast element** on the page — but not the loudest
### **Decision guidance**
**Choose your launcher color based on your website background:**
* **Light websites**
→ Use a darker or more saturated brand color
* **Dark websites**
→ Use a lighter brand variant or secondary brand color
* **Colorful or image-heavy pages**
→ Use a solid, flat color with strong contrast
(avoid gradients or transparency)
\
**Safe default (if unsure)**
* Use your **primary brand color**
* No gradients
* No transparency
* Solid fill with a clear icon
This ensures immediate visibility and recognizability.
**Avoid**
* Using the same color as your main CTA buttons
(the launcher should not compete with checkout or signup)
* Low-contrast combinations (e.g. white icon on light color)
* Neon or overly saturated colors that vibrate against the page
\
**The eye-catcher (optional, but powerful)**
An \*\*eye-catcher\*\* is a short piece of text shown next to or attached to the launcher. Its purpose is not decoration — it explains why someone should click.
**When to use an eye-catcher**
* For first-time visitors
* On content-heavy pages
* If chat usage is lower than expected
\
**Eye-catcher copy guidelines**
* Keep it **short (1–3 words)**
* Use **action or intent-based language**
* Make it human, not promotional
\
**Good examples**
* “Need help?”
* “Questions?”
* “Ask us”
* “Chat with us”
\
**Avoid**
* Full sentences
* Marketing slogans
* Urgent or pushy language (“Act now”, “Don’t miss out”)
\
**Message layout**
**Decisions**
* Differentiate end-user, human support and agent messages colour
* The colours need to be different enough, so that at a glance you know which message is from the chatter on your website, from the AI agent and which is from human support
* Alternatively you can keep the colours of the AI Agent and human support answers the same
* Aviod changing the border radius per message type, this can cause confusion.
## **Embedded vs floating widgets**
### **Floating widget**
* Decide whether the widget icon fits best on the left or right on your website
* Ensure it is not blocking any important content or buttons
* Clear launcher visibility matters most
* Alternatively, you can set your widget up to open automatically whenever someone visits the website
### **Embedded widget**
* Reduce borders and shadows, this feels outdated
* Match page background, but make it standout enough so it is clear you can chat
* Make it feel native to the page layout
## **Visual red flags (quick fixes)**
**Don’t**
* White icons on light buttons
* Full-brand-color backgrounds
* Multiple avatar styles
**Do**
* Neutral backgrounds
* One brand color, used intentionally
* System fonts for chat text
* One consistent visual system
## **Final checklist**
Before publishing:
Does this match our website's look and feel?
Is everything readable in long conversations?
Is the avatar intentional and consistent?
Does the launcher clearly invite interaction?
Would this still look good with minimal colour?
Is the text and the widget readable on my website?
## **When to revisit your widget design**
Re-evaluate your widget if:
* You rebrand
* Your website design changes
* Engagement drops or bounce increases
* You shift from support-only to sales conversations
Your widget is part of your product — not a one-time setup.
### **Final note**
If users trust how your widget looks, they’re more likely to trust what it says.
Design it intentionally. You’re in control.