Chat widget style guide

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.

​

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

Everything below explains how to apply this.

​

Core design principles

​

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
• Adobe Color – Accessibility tools

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”

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

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:

​

When to revisit your widget design

​

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.