CSS Customization

Learn how to customize the look and feel of the Pupau assistant to match your brand, using CSS variables.

How It Works

The Pupau Web Component uses Shadow DOM for style isolation. This means your site's CSS won't accidentally affect the assistant, and the assistant's styles won't leak into your page.

The way to customize the component is through CSS variables (custom properties), which are the only values that cross the Shadow DOM boundary.

/* Your site's CSS - does NOT affect the assistant */
body {
  font-family: Arial;
  color: red;
}

/* CSS variables - DO affect the assistant */
pupau-assistant {
  --pupau-color-accent: #ff6b6b;
}

All variables follow the --pupau-* naming convention.

Themes

The assistant supports three theme modes, controlled via the color-theme attribute:

<pupau-assistant color-theme="LIGHT"></pupau-assistant>  <!-- Default -->
<pupau-assistant color-theme="DARK"></pupau-assistant>
<pupau-assistant color-theme="AUTO"></pupau-assistant>   <!-- Follows OS preference -->

Value	Behavior
`LIGHT`	Always uses light colors (default)
`DARK`	Always uses dark colors
`AUTO`	Automatically follows the user's OS `prefers-color-scheme` setting

Lowercase values (light, dark, auto) are also accepted.

You can also set the theme via CSS class:

<pupau-assistant class="theme-dark"></pupau-assistant>

Overriding Dark Mode Variables

When dark mode is active, all variables automatically switch to their dark equivalents. You can further override specific values:

pupau-assistant.theme-dark {
  --pupau-bg-primary: #0d0d0d;
  --pupau-color-accent: #7c3aed;
}

See Dark Mode Defaults for the full list of dark mode values.

CSS Variables Reference

All variables listed below show their light mode default values. Set any of them on pupau-assistant to customize the component.

Colors

pupau-assistant {
  /* Brand */
  --pupau-color-primary: #eff6ff;
  --pupau-color-accent: #3b82f6;
  --pupau-color-secondary: #9c27b0;

  /* Functional */
  --pupau-color-success: #4caf50;
  --pupau-color-warning: #ff9800;
  --pupau-color-error: #ff6b7f;
  --pupau-color-info: #2196f3;

  /* Interactive states */
  --pupau-color-hover: #2563eb;
  --pupau-color-active: #1d4ed8;
  --pupau-color-disabled: #a1a1aa;
}

Backgrounds

pupau-assistant {
  --pupau-bg-primary: #ffffff;
  --pupau-bg-secondary: #f4f4f5;
  --pupau-bg-message-sent: #eff6ff;
  --pupau-bg-message-received: #ffffff;
  --pupau-bg-header: #fafafa;
  --pupau-bg-footer: #ffffff;
  --pupau-bg-hover: #f4f4f5;
  --pupau-bg-modal: #ffffff;
  --pupau-bg-overlay: rgba(0, 0, 0, 0.5);
  --pupau-bg-error: #ffebee;
  --pupau-bg-glassmorphism: rgba(240, 240, 240, 0.5);
  --pupau-bg-evaluate: #fff8b1;
  --pupau-bg-success: #e8f5e9;
  --pupau-bg-warning: #faebd7;
}

Text

pupau-assistant {
  --pupau-text-primary: #18181b;
  --pupau-text-secondary: #52525b;
  --pupau-text-disabled: #a1a1aa;
  --pupau-text-inverse: #ffffff;
  --pupau-text-link: #3b82f6;
  --pupau-text-link-hover: #2563eb;
  --pupau-text-muted: #71717a;
  --pupau-text-hint: #71717a;
  --pupau-text-heading: 1.75rem;       /* Heading size in forms */
}

Spacing

All spacing values are derived from --pupau-spacing-base. Change the base value to proportionally scale all spacing.

pupau-assistant {
  --pupau-spacing-base: 8px;

  --pupau-spacing-xxs: calc(var(--pupau-spacing-base) * 0.5);   /* 4px */
  --pupau-spacing-xs:  calc(var(--pupau-spacing-base) * 0.75);  /* 6px */
  --pupau-spacing-sm:  var(--pupau-spacing-base);               /* 8px */
  --pupau-spacing-md:  calc(var(--pupau-spacing-base) * 2);     /* 16px */
  --pupau-spacing-lg:  calc(var(--pupau-spacing-base) * 3);     /* 24px */
  --pupau-spacing-xl:  calc(var(--pupau-spacing-base) * 4);     /* 32px */
  --pupau-spacing-xxl: calc(var(--pupau-spacing-base) * 6);     /* 48px */
}

Typography

pupau-assistant {
  --pupau-font-family: 'Poppins', sans-serif;
  --pupau-font-size-xs: 0.75rem;        /* 12px */
  --pupau-font-size-sm: 0.875rem;       /* 14px */
  --pupau-font-size-base: 1rem;         /* 16px */
  --pupau-font-size-lg: 1.125rem;       /* 18px */
  --pupau-line-height-base: 1.5;
  --pupau-font-weight-medium: 500;
  --pupau-font-weight-semibold: 600;
}

Note: Custom fonts must be loaded in your page's <head>. The component will inherit the font family but cannot load external fonts on its own. See Custom Font example.

Border & Radius

All radius values are derived from --pupau-radius-base. Change the base value to scale all border radii.

pupau-assistant {
  --pupau-border-width: 1px;
  --pupau-border-color: #e4e4e7;
  --pupau-radius-base: 4px;

  --pupau-radius-sm:   var(--pupau-radius-base);                  /* 4px */
  --pupau-radius-md:   calc(var(--pupau-radius-base) * 2);        /* 8px */
  --pupau-radius-lg:   calc(var(--pupau-radius-base) * 4);        /* 16px */
  --pupau-radius-xl:   calc(var(--pupau-radius-base) * 4.5);      /* 18px */
  --pupau-radius-full: 9999px;
}

Shadows

pupau-assistant {
  --pupau-shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.12);
  --pupau-shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
  --pupau-shadow-lg: 0 10px 20px rgba(0, 0, 0, 0.15);
  --pupau-shadow-xl: 0 20px 40px rgba(0, 0, 0, 0.2);
}

Transitions

pupau-assistant {
  --pupau-transition-fast: 150ms ease;
  --pupau-transition-base: 300ms ease;
  --pupau-transition-slow: 500ms ease;
}

Layout & Dimensions

pupau-assistant {
  /* Structure */
  --pupau-header-height: 120px;
  --pupau-footer-height: 116px;

  /* Floating mode */
  --pupau-floating-width: 600px;
  --pupau-floating-height: 800px;
  --pupau-floating-max-width: 60%;
  --pupau-floating-max-height: 90%;

  /* Open button (floating mode only) */
  --pupau-open-button-size: 60px;

  /* Z-index */
  --pupau-z-modal: 10000;
  --pupau-z-floating: 99999999999;
}

Component-Specific Variables

pupau-assistant {
  --pupau-bg-tooltip: #000000;
  --pupau-text-tooltip: #ffffff;
}

Loading Indicator

pupau-assistant {
  --pupau-bg-loading-dot: #000000;
}

Starter Bar

pupau-assistant {
  --pupau-starter-bg: rgba(240, 240, 240, 0.5);
  --pupau-starter-backdrop-filter: blur(10px);
  --pupau-starter-border: 1px solid rgba(255, 255, 255, 0.3);
}

pupau-assistant {
  --pupau-mention-border: #e4e4e7;
  --pupau-mention-bg: #ffffff;
  --pupau-mention-text: #18181b;
  --pupau-mention-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
}

Nerd Stats Panel

pupau-assistant {
  --pupau-nerd-stats-font-size: 0.625rem;
  --pupau-nerd-stats-padding-y: var(--pupau-spacing-xxs);
  --pupau-nerd-stats-padding-x: var(--pupau-spacing-sm);
  --pupau-nerd-stats-gap: var(--pupau-spacing-xs);
  --pupau-nerd-stats-icon-size: 16px;
  --pupau-nerd-stats-margin-top: var(--pupau-spacing-sm);
}

Form Variables

Inputs

pupau-assistant {
  --pupau-input-h: 44px;
  --pupau-input-p-y: 12px;
  --pupau-input-p-x: var(--pupau-spacing-md);
  --pupau-input-border: 2px;
  --pupau-input-bg: var(--pupau-bg-primary);
  --pupau-input-border-color: var(--pupau-border-color);
  --pupau-input-radius: var(--pupau-radius-md);
}

Focus States

pupau-assistant {
  --pupau-focus-ring: 0 0 0 3px rgba(59, 130, 246, 0.12);
  --pupau-focus-border: var(--pupau-color-accent);
}

Buttons

pupau-assistant {
  --pupau-btn-h: 48px;
  --pupau-btn-p-y: 14px;
  --pupau-btn-p-x: var(--pupau-spacing-xl);
  --pupau-btn-radius: var(--pupau-radius-md);
  --pupau-btn-bg: var(--pupau-color-accent);
  --pupau-btn-bg-hover: #2563eb;
  --pupau-btn-text: var(--pupau-text-inverse);
  --pupau-btn-shadow-hover: 0 4px 12px rgba(59, 130, 246, 0.35);
  --pupau-btn-disabled-bg: #a1a1aa;
  --pupau-btn-disabled-opacity: 0.6;
}

Form Layout

pupau-assistant {
  --pupau-form-max-w: 480px;
  --pupau-form-gap: 1.5rem;
  --pupau-textarea-min-h: 110px;
}

Checkbox & Radio

pupau-assistant {
  --pupau-checkbox-size: 20px;
  --pupau-checkbox-accent: var(--pupau-color-accent);
}

Examples

Brand Colors

Inline via the style attribute:

<pupau-assistant
  token="your-token"
  style="
    --pupau-color-accent: #ff6b6b;
    --pupau-bg-message-sent: #ffe66d;
    --pupau-bg-message-received: #f0f0f0;
  ">
</pupau-assistant>

Or in a separate stylesheet:

pupau-assistant {
  --pupau-color-accent: #ff6b6b;
  --pupau-bg-message-sent: #ffe66d;
  --pupau-bg-message-received: #f0f0f0;
}

Dark Mode with Custom Accent

<pupau-assistant color-theme="DARK"></pupau-assistant>

pupau-assistant.theme-dark {
  --pupau-bg-primary: #0d0d0d;
  --pupau-color-accent: #7c3aed;
}

Automatic Dark Mode

No CSS required -- just set the attribute and the component adapts to the user's OS preference:

<pupau-assistant color-theme="AUTO"></pupau-assistant>

Custom Font

pupau-assistant {
  --pupau-font-family: 'Inter', -apple-system, sans-serif;
  --pupau-font-size-base: 0.875rem;
  --pupau-font-size-lg: 1rem;
}

Load the font in your page's <head>:

<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet">

Floating Chat Size

pupau-assistant {
  --pupau-floating-width: 400px;
  --pupau-floating-height: 600px;
  --pupau-open-button-size: 52px;
  --pupau-shadow-lg: 0 10px 40px rgba(0, 0, 0, 0.25);
  --pupau-radius-lg: 24px;
}

Responsive Layout

pupau-assistant {
  --pupau-floating-width: 600px;
  --pupau-font-size-base: 1rem;
}

@media (max-width: 768px) {
  pupau-assistant {
    --pupau-floating-width: 90vw;
    --pupau-font-size-base: 0.875rem;
  }
}

@media (max-width: 480px) {
  pupau-assistant {
    --pupau-floating-width: 100vw;
    --pupau-floating-height: 100vh;
    --pupau-radius-lg: 0;
  }
}

Mode-Specific Styles

Target variables depending on the display mode:

/* Floating mode only */
pupau-assistant[mode="FLOATING"] {
  --pupau-shadow-lg: 0 20px 60px rgba(0, 0, 0, 0.3);
}

/* Full-page mode only */
pupau-assistant[mode="FULL"] {
  --pupau-bg-primary: transparent;
}

Preset Themes

Copy-paste these ready-made themes as a starting point.

Deep Dark

pupau-assistant {
  --pupau-color-accent: #64b5f6;
  --pupau-color-secondary: #ab47bc;

  --pupau-bg-primary: #121212;
  --pupau-bg-secondary: #1e1e1e;
  --pupau-bg-header: #1a1a1a;
  --pupau-bg-footer: #1a1a1a;
  --pupau-bg-message-sent: #1976d2;
  --pupau-bg-message-received: #2a2a2a;
  --pupau-bg-hover: #333333;
  --pupau-bg-modal: #242424;
  --pupau-bg-overlay: rgba(0, 0, 0, 0.7);

  --pupau-text-primary: #e0e0e0;
  --pupau-text-secondary: #b0b0b0;
  --pupau-text-disabled: #666666;
  --pupau-text-inverse: #121212;

  --pupau-border-color: #3a3a3a;

  --pupau-shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.3);
  --pupau-shadow-md: 0 4px 6px rgba(0, 0, 0, 0.4);
  --pupau-shadow-lg: 0 10px 20px rgba(0, 0, 0, 0.5);
}

Corporate

pupau-assistant {
  --pupau-color-accent: #0052cc;
  --pupau-color-secondary: #5e6c84;

  --pupau-bg-primary: #ffffff;
  --pupau-bg-secondary: #f4f5f7;
  --pupau-bg-header: #fafbfc;
  --pupau-bg-footer: #ffffff;
  --pupau-bg-message-sent: #deebff;
  --pupau-bg-message-received: #f4f5f7;
  --pupau-bg-hover: #ebecf0;

  --pupau-text-primary: #172b4d;
  --pupau-text-secondary: #5e6c84;

  --pupau-radius-sm: 3px;
  --pupau-radius-md: 6px;
  --pupau-radius-lg: 8px;

  --pupau-shadow-md: 0 2px 8px rgba(0, 82, 204, 0.15);
  --pupau-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}

Dark Mode Defaults

When dark mode is active (via color-theme="DARK" or color-theme="AUTO" with a dark OS), the following default values apply. You can override any of them.

/* Colors */
--pupau-color-primary: #60a5fa;
--pupau-color-accent: #60a5fa;
--pupau-color-secondary: #c77dff;
--pupau-color-success: #6ee7b7;
--pupau-color-warning: #fbbf24;
--pupau-color-error: #f87171;
--pupau-color-info: #60a5fa;
--pupau-color-hover: #93c5fd;
--pupau-color-active: #bfdbfe;
--pupau-color-disabled: #71717a;

/* Backgrounds */
--pupau-bg-primary: #18181b;
--pupau-bg-secondary: #27272a;
--pupau-bg-message-sent: color-mix(in srgb, #60a5fa 16%, transparent);
--pupau-bg-message-received: #27272a;
--pupau-bg-header: #18181b;
--pupau-bg-footer: #18181b;
--pupau-bg-hover: #3f3f46;
--pupau-bg-modal: #27272a;
--pupau-bg-overlay: rgba(0, 0, 0, 0.75);
--pupau-bg-error: #3d1f1f;
--pupau-bg-glassmorphism: rgba(39, 39, 42, 0.6);
--pupau-bg-evaluate: #4a4a2a;
--pupau-bg-success: #1a3a1a;
--pupau-bg-warning: #3a2a1a;

/* Text */
--pupau-text-primary: rgba(255, 255, 255, 0.87);
--pupau-text-secondary: #a1a1aa;
--pupau-text-disabled: #71717a;
--pupau-text-inverse: #18181b;
--pupau-text-link: #60a5fa;
--pupau-text-link-hover: #93c5fd;
--pupau-text-hint: #a1a1aa;
--pupau-text-muted: #71717a;

/* Borders */
--pupau-border-color: #3f3f46;

/* Shadows */
--pupau-shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.3);
--pupau-shadow-md: 0 4px 6px rgba(0, 0, 0, 0.4);
--pupau-shadow-lg: 0 10px 20px rgba(0, 0, 0, 0.5);
--pupau-shadow-xl: 0 20px 40px rgba(0, 0, 0, 0.6);

/* Starter bar */
--pupau-starter-bg: rgba(39, 39, 42, 0.7);
--pupau-starter-border: 1px solid rgba(161, 161, 170, 0.4);

/* Mention dropdown */
--pupau-mention-border: #3f3f46;
--pupau-mention-bg: #27272a;
--pupau-mention-text: rgba(255, 255, 255, 0.95);
--pupau-mention-shadow: 0 1px 3px rgba(0, 0, 0, 0.3);

/* Tooltip & loading */
--pupau-bg-tooltip: #27272a;
--pupau-text-tooltip: rgba(255, 255, 255, 0.87);
--pupau-bg-loading-dot: rgba(255, 255, 255, 0.87);

/* Form */
--pupau-input-bg: #27272a;
--pupau-input-border-color: #3f3f46;
--pupau-focus-ring: 0 0 0 3px rgba(96, 165, 250, 0.25);
--pupau-focus-border: #60a5fa;
--pupau-btn-bg-hover: #93c5fd;
--pupau-btn-shadow-hover: 0 4px 12px rgba(96, 165, 250, 0.5);
--pupau-btn-disabled-bg: #3f3f46;
--pupau-btn-text: #18181b;

Troubleshooting

My CSS variables are not working

Check the syntax -- variables must start with --:

/* Wrong */
pupau-assistant { pupau-color-accent: #ff0000; }

/* Correct */
pupau-assistant { --pupau-color-accent: #ff0000; }

Check the variable name -- use the exact names from this reference:

/* Wrong -- this variable does not exist */
pupau-assistant { --pupau-message-background: #fff; }

/* Correct */
pupau-assistant { --pupau-bg-message-sent: #fff; }

Custom font is not applied

Fonts must be loaded in your page's <head>, not inside the component. The component inherits the font family via the CSS variable but cannot load external resources.

<head>
  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet">
</head>
<style>
  pupau-assistant {
    --pupau-font-family: 'Inter', sans-serif;
  }
</style>

I can't target elements inside the component

This is expected. The Shadow DOM isolates internal styles by design. Use CSS variables instead of selectors:

/* This will never work */
pupau-assistant .message { color: red; }

/* Use variables instead */
pupau-assistant { --pupau-bg-message-received: #f0f0f0; }

Dark mode does not activate automatically

Make sure you're using color-theme="AUTO":

<pupau-assistant color-theme="AUTO"></pupau-assistant>

Quick Reference

`color-theme` Attribute

Value	Behavior
`LIGHT` (default)	Always light mode
`DARK`	Always dark mode
`AUTO`	Follows OS preference

Variable Groups (~100 total)

Group	Count	Prefix
Colors	10	`--pupau-color-*`
Backgrounds	14	`--pupau-bg-*`
Text	9	`--pupau-text-*`
Spacing	9	`--pupau-spacing-*`
Typography	8	`--pupau-font-`, `--pupau-line-height-`
Border & Radius	7	`--pupau-border-`, `--pupau-radius-`
Shadows	4	`--pupau-shadow-*`
Transitions	3	`--pupau-transition-*`
Layout	9	`--pupau-header-`, `--pupau-footer-`, `--pupau-floating-*`
Starter Bar	3	`--pupau-starter-*`
Mention Dropdown	4	`--pupau-mention-*`
Nerd Stats	6	`--pupau-nerd-stats-*`
Form / Input	7	`--pupau-input-*`
Form / Button	10	`--pupau-btn-*`
Form / Focus	2	`--pupau-focus-*`
Form / Layout	3	`--pupau-form-`, `--pupau-textarea-`
Checkbox	2	`--pupau-checkbox-*`
Tooltip	2	`--pupau-bg-tooltip`, `--pupau-text-tooltip`
Loading	1	`--pupau-bg-loading-dot`

How It Works​

Themes​

Overriding Dark Mode Variables​

CSS Variables Reference​

Colors​

Backgrounds​

Text​

Spacing​

Typography​

Border & Radius​

Shadows​

Transitions​

Layout & Dimensions​

Component-Specific Variables​

Tooltip​

Loading Indicator​

Starter Bar​

Mention Dropdown​

Nerd Stats Panel​

Form Variables​

Inputs​

Focus States​

Buttons​

Form Layout​

Checkbox & Radio​

Examples​

Brand Colors​

Dark Mode with Custom Accent​

Automatic Dark Mode​

Custom Font​

Floating Chat Size​

Responsive Layout​

Mode-Specific Styles​

Preset Themes​

Deep Dark​

Corporate​

Dark Mode Defaults​

Troubleshooting​

My CSS variables are not working​

Custom font is not applied​

I can't target elements inside the component​

Dark mode does not activate automatically​

Quick Reference​

color-theme Attribute​

Variable Groups (~100 total)​