# Appearance and styling

> Theme the UI Kit with variables, dark colors, slot classes, CSS parts, your own stylesheet and locale text.

UI Kit components use one shared stylesheet. You can change it at five levels, from
lightest to fullest control: variables, dark colors, slot classes and styles,
your own CSS, and unstyled mode.

Pass an `appearance` object to `PolymorfaProvider`, to `definePolymorfa()`, or
to an element's `configuration` property:

**React**

```tsx
<PolymorfaProvider
  tokenEndpoint="/api/polymorfa/token"
  appearance={{
    theme: "system",
    variables: { colorPrimary: "#0f766e", radiusMedium: "8px" },
    darkVariables: { colorPrimary: "#14b8a6" },
    elements: { bubble: { styles: { borderRadius: "6px" } } },
  }}
>
  <Inbox />
</PolymorfaProvider>
```

**Web Components**

```ts
import { definePolymorfa } from "@polymorfa/elements";

definePolymorfa({
  tokenEndpoint: "/api/polymorfa/token",
  appearance: {
    theme: "system",
    variables: { colorPrimary: "#0f766e" },
    darkVariables: { colorPrimary: "#14b8a6" },
  },
});

// Or per element:
document.querySelector("pmfa-message-list").configuration = {
  appearance: { theme: "dark" },
};
```

## Appearance fields

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `"light" \| "dark" \| "system"` | `"system"` | `system` follows the operating system's color scheme. |
| `variables` | `Partial<AppearanceVariables>` | See below | Colors, type, spacing, radii, shadow and motion. |
| `darkVariables` | `Partial<AppearanceVariables>` | Built-in dark palette | Dark theme colors. Only color keys apply. |
| `layout` | `Partial<AppearanceLayout>` | See below | Text direction and drawer width. |
| `elements` | `Record<slot, { className?, styles?, surface? }>` | `{}` | Class names and inline styles for one [slot](#slots). |
| `unstyled` | `boolean` | `false` | Skip the bundled stylesheet. Components keep their classes, slots and parts. |

## Variables

Each variable becomes a CSS custom property on the component root.

| Variable | CSS property | Default |
| --- | --- | --- |
| `colorPrimary` | `--pmfa-color-primary` | `#5b4bf7` |
| `colorBackground` | `--pmfa-color-background` | `#ffffff` |
| `colorForeground` | `--pmfa-color-foreground` | `#17151f` |
| `colorMuted` | `--pmfa-color-muted` | `#6d6878` |
| `colorBorder` | `--pmfa-color-border` | `#dedbe5` |
| `colorDanger` | `--pmfa-color-danger` | `#c62828` |
| `colorSuccess` | `--pmfa-color-success` | `#18794e` |
| `fontFamily` | `--pmfa-font-family` | `Inter, ui-sans-serif, system-ui, sans-serif` |
| `fontSizeBase` | `--pmfa-font-size-base` | `16px` |
| `spacingSmall` | `--pmfa-spacing-small` | `8px` |
| `spacingMedium` | `--pmfa-spacing-medium` | `12px` |
| `spacingLarge` | `--pmfa-spacing-large` | `20px` |
| `radiusSmall` | `--pmfa-radius-small` | `6px` |
| `radiusMedium` | `--pmfa-radius-medium` | `10px` |
| `radiusLarge` | `--pmfa-radius-large` | `16px` |
| `shadowPanel` | `--pmfa-shadow-panel` | `0 18px 50px rgb(23 21 31 / 0.16)` |
| `motion` | `--pmfa-motion` | `system` (`full`, `reduced` or `system`) |

### Layout

| Field | Default | Description |
| --- | --- | --- |
| `direction` | `"auto"` | `ltr` or `rtl`. `auto` uses the locale's direction. |
| `drawerWidth` | `400px` | Width of the chat drawer, set as `--pmfa-drawer-width`. |

`density`, `dialogWidth` and `callAspectRatio` are accepted, but no component
reads them in the current prerelease.

### Dark colors

`theme: "dark"` uses the dark palette. `theme: "system"` uses it when the
system prefers dark. `darkVariables` overrides dark colors one at a time and is
emitted as `--pmfa-dark-color-*`, for example `--pmfa-dark-color-primary`.
Unset dark colors use the built-in dark palette, except `colorPrimary`, which
falls back to your light primary.

### Chat variables

Chat surfaces derive their colors from the variables above. Set these custom
properties on any ancestor to change one surface:

| Variable | Default |
| --- | --- |
| `--pmfa-chat-background` | A light tint of the background and primary |
| `--pmfa-chat-panel` | The background color |
| `--pmfa-chat-pattern` | A faint dot grid. Set `none` to remove it. |
| `--pmfa-bubble-incoming` | The background color |
| `--pmfa-bubble-outgoing` | The primary color at 13% on the background |
| `--pmfa-bubble-outgoing-text` | The foreground color |
| `--pmfa-bubble-radius` | `8px` |
| `--pmfa-message-font-size` | `0.9375em` |
| `--pmfa-receipt-read` | A blue for read and played receipts |
| `--pmfa-unread` | The primary color, for unread badges |

Each has a `--pmfa-dark-*` counterpart, such as `--pmfa-dark-bubble-outgoing`,
except `--pmfa-chat-pattern`, `--pmfa-bubble-radius`,
`--pmfa-message-font-size` and `--pmfa-unread`.

### Call variables

Call components read the shared variables: the accent follows
`colorForeground`, Answer uses `colorSuccess`, Decline and Hang up use
`colorDanger`, and cards use `colorBackground`, `colorMuted`, `colorBorder`,
`radiusMedium` and `fontFamily`. The call stage is always dark. Call styles are
scoped under the `.pmfa-calls` class.

## Override with your own CSS

Every bundled rule sits in the `polymorfa` cascade layer. Any unlayered CSS in
your app overrides it, whatever its specificity:

```css
.pmfa-bubble {
  border-radius: 6px;
}
```

## Slots

Every structural node has a slot name. Use it three ways:

- `appearance.elements[slot]` adds a `className` and inline `styles` to the
  node. Style keys can be camelCase, kebab-case or custom properties.
- React components take a `classNames` prop keyed by slot, and set
  `data-slot` on each node.
- Web Components add the slot's part name to the node's `part` attribute, for
  `::part()` selectors.

```tsx
<MessageList
  controller={conversation}
  classNames={{ messageList: "my-log", dateSeparator: "my-date" }}
/>
```

```css
pmfa-message-list::part(bubble) {
  border-radius: 6px;
}
pmfa-chat-drawer::part(drawer-header) {
  background: #0f766e;
  color: white;
}
```

| Slot | Part | Node |
| --- | --- | --- |
| `chatWindow` | `chat-window` | Inline chat window |
| `chatHeader` | `chat-header` | Chat window header |
| `chatFooter` | `chat-footer` | Chat window footer |
| `messageList` | `message-list` | Scrolling message log |
| `message` | `message` | One message row |
| `bubble` | `bubble` | Message bubble |
| `messageMeta` | `message-meta` | Time and delivery status |
| `messageActions` | `message-actions` | Reply and Retry group |
| `replyButton` | `reply-button` | Reply action |
| `retryButton` | `retry-button` | Retry action on a failed message |
| `attachment` | `attachment` | Image thumbnail or file card |
| `replyQuote` | `reply-quote` | Quoted message above a reply |
| `dateSeparator` | `date-separator` | "Today", "Yesterday" or a date |
| `loadMore` | `load-more` | Load earlier messages button |
| `latestButton` | `latest-button` | Jump to the latest message |
| `empty` | `empty` | Empty conversation text |
| `composer` | `composer` | Composer form |
| `composerInput` | `composer-input` | Message field |
| `composerSend` | `composer-send` | Send button |
| `composerAttach` | `composer-attach` | Attach button |
| `composerToolbar` | `composer-toolbar` | Composer button and field row |
| `emojiButton` | `emoji-button` | Emoji picker button |
| `emojiPicker` | `emoji-picker` | Emoji picker popover |
| `voiceButton` | `voice-button` | Record voice note button |
| `recordingBar` | `recording-bar` | Voice note recording bar |
| `quickReplyMenu` | `quick-reply-menu` | Quick reply list |
| `attachmentChip` | `attachment-chip` | Pending attachment |
| `replyBanner` | `reply-banner` | "Replying to" banner |
| `drawer` | `drawer` | Drawer panel |
| `drawerHeader` | `drawer-header` | Drawer header |
| `drawerTitle` | `drawer-title` | Drawer title |
| `drawerClose` | `drawer-close` | Drawer close button |
| `templateBuilder` | `template-builder` | Template editor panel |
| `field` | `field` | Labelled field or field group |
| `label` | `label` | Field label |
| `input` | `input` | Template input or text area |
| `actions` | `actions` | Template action row |
| `primaryButton` | `primary-button` | Save draft |
| `button` | `button` | Preview and Submit to Meta |
| `preview` | `preview-panel` | Template preview area |
| `error` | `error` | Error message |
| `inbox` | `inbox` | Inbox root |
| `conversationList` | `conversation-list` | Conversation list |
| `conversationSearch` | `conversation-search` | Conversation search field |
| `conversationItem` | `conversation-item` | One conversation row |
| `avatar` | `avatar` | Contact avatar |
| `unreadBadge` | `unread-badge` | Unread count |
| `thread` | `thread` | Open conversation |
| `threadHeader` | `thread-header` | Open conversation header |
| `backButton` | `back-button` | Back to the list on narrow screens |
| `contactPanel` | `contact-panel` | Contact panel |
| `connectButton` | `connect-button` | Connect WhatsApp button |
| `sessionStatus` | `session-status` | Connection status badge |
| `callButton` | `call-button` | Call button |
| `templateManager` | `template-manager` | Template manager |
| `templateList` | `template-list` | Template list |
| `templateItem` | `template-item` | One template row |

The `preview` slot uses the part name `preview-panel`, because the Preview
button already uses `preview`. Web Components also keep earlier part names,
such as `meta`, `input`, `send`, `header`, `title` and `close`.

## Web Component stylesheets

For rules that `::part()` cannot express, such as descendants or states, set
`configuration.stylesheet`. It takes CSS text, a `CSSStyleSheet`, or an array
of either, and is applied inside the shadow root after the default stylesheet:

```ts
element.configuration = {
  appearance: { theme: "dark" },
  stylesheet: `.pmfa-msg-out .pmfa-bubble { border-end-end-radius: 18px; }`,
};
```

## Unstyled mode

`unstyled: true` skips the bundled stylesheet. Components still render their
`pmfa-*` classes, `data-slot` attributes (React) and part names (Web
Components), so you can style them from scratch. With Web Components, your
`configuration.stylesheet` is the only stylesheet in the shadow root.

> **Note**
>
> React adds the bundled stylesheet to the document once, the first time a styled
> component mounts, and it stays. Its rules then also match unstyled React
> components on the same page. Use `unstyled: true` for every React component on
> the page, or override the bundled rules with unlayered CSS. Web Components keep
> styles inside each shadow root and are not affected.

## Locale and text

All visible text comes from the locale. The default is English. Create a
locale with `createLocale(code, messages, direction)` from `@polymorfa/ui`,
overriding any message key; unset keys use English.

```tsx
import { createLocale } from "@polymorfa/ui";

const locale = createLocale("en-GB", {
  "composer.placeholder": "Write a reply",
  "templates.empty": "No templates yet",
});

<PolymorfaProvider tokenEndpoint="/api/polymorfa/token" locale={locale}>
  <Inbox />
</PolymorfaProvider>;
```

`ENGLISH_MESSAGES` lists every key. The direction is `rtl` for Arabic, Persian,
Hebrew, Pashto and Urdu codes and `ltr` otherwise; pass `"ltr"` or `"rtl"` as
the third argument to set it. Message times and dates are formatted for the
locale code.

## Reduced motion

All components stop animations and transitions when the user's system sets
`prefers-reduced-motion: reduce`. The `motion` variable is emitted as
`--pmfa-motion` for your own CSS; the bundled stylesheet follows the system
setting.
