> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vizochok.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Theming

> Customize the widget appearance to match your brand

## Theme Configuration

Pass a `theme` object in the widget config to customize the visual appearance:

```typescript theme={null}
const widget = new VizochokWidget({
  apiKey: 'pk_your_key',
  storeId: 'your-store',
  theme: {
    primaryColor: '#1a73e8',
    fontFamily: "'Roboto', sans-serif",
    borderRadius: '12px',
    mode: 'auto',
    currency: '$',
  },
});
```

### Theme Properties

<ParamField body="primaryColor" type="string" default="#2D8A4E">
  The primary brand color used throughout the widget. Applied to:

  * Toggle button background
  * Chat header background
  * Send button
  * User message bubbles
  * Active/selected states (quick replies, checkboxes)
  * Product "Add" button hover state
  * Promo price highlight
  * Text selection highlight
  * Focus outlines
</ParamField>

<ParamField body="fontFamily" type="string" default="'Inter', system-ui, -apple-system, sans-serif">
  CSS font-family stack for all widget text. The widget also uses a separate monospace font (`'JetBrains Mono', ui-monospace, 'SF Mono', monospace`) for prices, counters, and status indicators -- this cannot be overridden.
</ParamField>

<ParamField body="borderRadius" type="string" default="0px">
  Base border radius for the chat panel, product cards, quick reply buttons, and other elements. Inner elements automatically use `calc(var(--vz-radius) - 4px)` for consistent visual nesting.

  Common values:

  * `'0px'` -- sharp corners (default)
  * `'8px'` -- subtle rounding
  * `'12px'` -- modern rounded look
  * `'16px'` -- heavily rounded
</ParamField>

<ParamField body="mode" type="'light' | 'dark' | 'auto'" default="light">
  Color scheme for the widget. See the sections below for details on each mode.
</ParamField>

<ParamField body="currency" type="string">
  Currency symbol displayed next to product prices and cart totals. Examples: `'$'`, `'EUR'`, `'GBP'`.
</ParamField>

## Light / Dark / Auto Mode

### Light Mode (default)

```typescript theme={null}
theme: { mode: 'light' }
```

| Token             | Value                    | Used For                     |
| ----------------- | ------------------------ | ---------------------------- |
| `--vz-bg`         | `#FBFEFC`                | Chat background, inputs      |
| `--vz-surface`    | `rgba(28, 25, 23, 0.02)` | Product cards, panels        |
| `--vz-text`       | `#1C1917`                | Primary text                 |
| `--vz-text-muted` | `#78716C`                | Secondary text, placeholders |
| `--vz-border`     | `rgba(28, 25, 23, 0.08)` | Borders, dividers            |
| `--vz-bot-bubble` | `rgba(28, 25, 23, 0.03)` | Bot message background       |

### Dark Mode

```typescript theme={null}
theme: { mode: 'dark' }
```

| Token             | Value     | Used For               |
| ----------------- | --------- | ---------------------- |
| `--vz-bg`         | `#0a0a0a` | Chat background        |
| `--vz-surface`    | `#18181b` | Product cards, panels  |
| `--vz-text`       | `#fafafa` | Primary text           |
| `--vz-text-muted` | `#a1a1aa` | Secondary text         |
| `--vz-border`     | `#27272a` | Borders, dividers      |
| `--vz-bot-bubble` | `#18181b` | Bot message background |

### Auto Mode

```typescript theme={null}
theme: { mode: 'auto' }
```

Automatically follows the user's operating system preference via `@media (prefers-color-scheme: dark)`. Defaults to light mode and switches to dark when the OS preference changes.

## Primary Color Examples

```typescript theme={null}
// Green (default -- VIZOCHOK brand)
theme: { primaryColor: '#2D8A4E' }

// Blue
theme: { primaryColor: '#1a73e8' }

// Purple
theme: { primaryColor: '#7C3AED' }

// Orange
theme: { primaryColor: '#EA580C' }

// Red
theme: { primaryColor: '#DC2626' }

// Black (minimal)
theme: { primaryColor: '#000000' }
```

## CSS Custom Properties Reference

All CSS custom properties used internally by the widget:

### Layout

| Property           | Default | Description                       |
| ------------------ | ------- | --------------------------------- |
| `--vz-chat-width`  | `400px` | Chat panel width (floating mode)  |
| `--vz-chat-height` | `600px` | Chat panel height (floating mode) |
| `--vz-toggle-size` | `56px`  | Toggle button diameter            |

### Colors

| Property                  | Light Default         | Dark Default |
| ------------------------- | --------------------- | ------------ |
| `--vz-primary`            | `#2D8A4E`             | `#2D8A4E`    |
| `--vz-primary-foreground` | `#ffffff`             | `#ffffff`    |
| `--vz-bg`                 | `#FBFEFC`             | `#0a0a0a`    |
| `--vz-surface`            | `rgba(28,25,23,0.02)` | `#18181b`    |
| `--vz-text`               | `#1C1917`             | `#fafafa`    |
| `--vz-text-muted`         | `#78716C`             | `#a1a1aa`    |
| `--vz-border`             | `rgba(28,25,23,0.08)` | `#27272a`    |
| `--vz-error`              | `#ef4444`             | `#f87171`    |
| `--vz-success`            | `#2D8A4E`             | `#2D8A4E`    |
| `--vz-warning`            | `#eab308`             | `#facc15`    |

### Typography

| Property           | Default                                         |
| ------------------ | ----------------------------------------------- |
| `--vz-font-family` | `'Inter', system-ui, -apple-system, sans-serif` |
| `--vz-mono`        | `'JetBrains Mono', ui-monospace, monospace`     |

### Effects

| Property          | Default                               |
| ----------------- | ------------------------------------- |
| `--vz-radius`     | `0px`                                 |
| `--vz-shadow-sm`  | `0 1px 3px rgba(28,25,23,0.06)`       |
| `--vz-shadow-md`  | `0 4px 12px rgba(28,25,23,0.08)`      |
| `--vz-shadow-lg`  | `0 8px 30px rgba(28,25,23,0.12)`      |
| `--vz-transition` | `200ms cubic-bezier(0.16, 1, 0.3, 1)` |

## CSS Isolation via Shadow DOM

The widget renders inside a [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) boundary, which provides full CSS isolation:

* **No style leaking** -- widget styles do not affect your page
* **No style inheritance** -- your page styles (Tailwind, Bootstrap, etc.) do not affect the widget
* **Reset via `all: initial`** -- the `:host` element resets all inherited CSS properties

The `ThemeConfig` API is the intended customization mechanism. You cannot target widget internals with external CSS selectors.

<Note>
  The Shadow DOM is created with `mode: 'open'`, so you can inspect the widget's internal structure in browser DevTools. For advanced customization, you can modify CSS custom properties at runtime via JavaScript:

  ```javascript theme={null}
  const host = document.querySelector('#vizochok-widget');
  const container = host?.shadowRoot?.querySelector('.vz-widget');
  container?.style.setProperty('--vz-chat-width', '450px');
  container?.style.setProperty('--vz-chat-height', '700px');
  ```
</Note>

## Visual Elements

The widget consists of these visual sections:

**Toggle Button** -- a circular floating action button (56px diameter) positioned in the bottom corner of the viewport. Uses `--vz-primary` as the background color. Shows an unread message badge when the chat is closed and new messages arrive.

**Chat Header** -- a colored bar at the top of the chat panel displaying the bot name, avatar, connection status indicator (green/yellow/red dot), new chat button, and close button.

**Message Area** -- a scrollable region displaying the conversation. User messages align right with the primary color background. Bot messages align left with transparent background. Supports rich content blocks: text, product cards, quick replies, ingredient checklists, meal plans, confirmation cards, session summaries, status indicators, and error messages.

**Input Area** -- a text area at the bottom with a circular send button. Supports multi-line input with auto-resize (max 120px height). Disabled state reduces opacity when the connection is lost.

**Product Cards** -- a list layout showing product name, price (with promo price support), and a quantity stepper with add button. Prices use the monospace font for alignment.

**Quick Replies** -- pill-shaped buttons that wrap to multiple lines. Clicking a reply sends it as a user message. The selected reply gets the primary color; others fade out.

## Responsive Behavior

The widget automatically adapts to the viewport:

* **Desktop** (640px+): floating panel with configured width/height, positioned in the corner
* **Mobile** (\<640px): full-screen overlay that slides up from the bottom with safe-area inset support for notched devices

On mobile:

* The toggle button is fixed at the bottom of the viewport
* The toggle button hides when the chat panel is open
* The chat panel uses `100dvh` for proper height on mobile browsers with address bars
* Scroll containment prevents background page scrolling

## Accessibility

Built-in accessibility features:

* All interactive elements meet the 44x44px minimum touch target size
* Focus indicators use a 2px outline in the primary color
* The toggle button includes `aria-label` and `aria-expanded` attributes
* `prefers-reduced-motion: reduce` disables all animations and transitions
* `@media print` hides the widget entirely
* Scrollbar styling supports both WebKit and Firefox (`scrollbar-width: thin`) APIs