> ## Documentation Index
> Fetch the complete documentation index at: https://velt-claude-ui-customization-docs-review-m7hwcn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CSS

> Theme Velt UI with CSS variables, dark mode tokens, and supported class overrides.

Change Velt's look (colors, spacing, fonts, radius, shadows) without touching its structure or behavior. It's the lowest-effort approach, and it layers on top of every other one.

<Info>
  Two shortcuts before you write any CSS: build a theme visually in the [Theme Playground](https://playground.velt.dev/themes), or have the [UI Customization Plugin](/get-started/ui-customization-plugin) extract the values from your Figma design and write the overrides for you.
</Info>

<Warning>
  `className` and `style` props on Velt components do nothing. Style Velt with the variables and classes below, or add classes to your own markup inside a [wireframe](/ui-customization/layout).
</Warning>

## Make your CSS reach Velt

Velt can render inside a shadow DOM, which blocks your stylesheets.

* **CSS variables** (`--velt-*`) always cross the boundary. Theming with variables alone needs nothing here.
* **Class and element selectors** don't. Pick one of these:

**Option A: turn shadow DOM off.**

<Tabs>
  <Tab title="React / Next.js">
    ```tsx theme={null}
    <VeltComments shadowDom={false} />
    <VeltCommentsSidebar shadowDom={false} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-comments shadow-dom="false"></velt-comments>
    <velt-comments-sidebar shadow-dom="false"></velt-comments-sidebar>
    ```
  </Tab>
</Tabs>

**Option B: keep it on and inject your CSS into the shadow root.** Use `type: "styles"` for a CSS string, `type: "link"` for a stylesheet URL.

<Tabs>
  <Tab title="React / Next.js">
    ```tsx theme={null}
    const { client } = useVeltClient();
    client.injectCustomCss({ type: "styles", value: `
      .velt-comment-dialog-composer { border-radius: 10px !important; }
    ` });
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```js theme={null}
    Velt.injectCustomCss({ type: "styles", value: `
      .velt-comment-dialog-composer { border-radius: 10px !important; }
    ` });
    ```
  </Tab>
</Tabs>

<Note>
  **Wireframes change this.** Registering a component's **root** wireframe (e.g. `VeltCommentDialogWireframe`) removes that component's shadow DOM automatically, so your class CSS reaches it. A **nested-only** wireframe doesn't: set `shadowDom={false}` yourself. Inline `style=""` always works either way.
</Note>

## Theme with variables

Put all Velt CSS in one stylesheet and override the tokens you need:

```css theme={null}
/* velt.css */
:root {
  --velt-light-mode-accent: #FF6B35;
  --velt-light-mode-accent-hover: #E55A29;
  --velt-light-mode-background-0: #FFFFFF;
  --velt-light-mode-text-0: #0A0A0A;

  --velt-border-radius-md: 10px;
  --velt-spacing-md: 14px;
  --velt-font-size-sm: 13px;
}
```

Every token is listed in [`CSS variables`](/ui-customization/reference/css-variables); don't invent names. Older surfaces read a few `--legacy-velt-*` tokens, which are listed there too.

<Tip>
  Rather than hand-picking values, build your theme in the [Theme Playground](https://playground.velt.dev/themes): adjust colors, radius, spacing, and typography against a live preview, then copy the generated variables straight into this stylesheet.
</Tip>

## Dark mode

Velt sets `data-velt-theme="dark"` on the document root when dark mode is on. You supply the values:

```css theme={null}
:root[data-velt-theme="dark"] {
  --velt-dark-mode-accent: #FF8A5C;
  --velt-dark-mode-background-0: #0F0F0F;
  --velt-dark-mode-text-0: #FFFFFF;
}
```

Turn it on with the `darkMode` prop (also `dialogDarkMode`, `pinDarkMode`, … for components Velt injects for you), with `setDarkMode()` app-wide, or by wiring your own `prefers-color-scheme` listener to it:

<Tabs>
  <Tab title="React / Next.js">
    ```tsx theme={null}
    // Global
    const { client } = useVeltClient();
    client.setDarkMode(true);

    // Per component
    <VeltComments darkMode={true} dialogDarkMode={true} pinDarkMode={true} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <script>
      Velt.setDarkMode(true);
    </script>

    <velt-comments dark-mode="true" dialog-dark-mode="true" pin-dark-mode="true"></velt-comments>
    ```
  </Tab>
</Tabs>

## Fonts

One global token sets the font across every Velt surface:

```css theme={null}
:root {
  --velt-default-font-family: "Inter", "Helvetica Neue", Arial, sans-serif;
}
```

Font sizes use the `--velt-font-size-*` scale. Line-height and weight are per-component.

## Override classes

For anything variables don't cover, target Velt's classes. **Velt's own styles are high-specificity, so your overrides need `!important`.** That's the supported way to do class-based Velt CSS, not a hack.

1. Run with `shadowDom={false}` and inspect the element.
2. Prefer its `velt-*` BEM class over the short legacy twin: `velt-comment-dialog--selected`, not `selected`.
3. Write the rule with `!important`:

```css theme={null}
.velt-composer--submit-button {
  background: #3d5afe !important;
  border-radius: 6px !important;
}
```

<Tip>
  [`CSS classes`](/ui-customization/reference/css-classes) lists every structural and stateful class (unread, resolved, selected, hover, filter-applied, …). Class names can shift between versions, so prefer a `--velt-*` variable where one exists and re-check overrides on upgrade.
</Tip>

## Unstyled mode

Restyling most of the UI anyway? Strip Velt's visual styling with [`setUnstyledMode()`](/api-reference/sdk/api/api-methods#setunstyledmode) (v6.0.0-beta.10+) and bring your own CSS. Layout and positioning styles are kept so components stay functional. It covers styles in the page head and inside shadow roots, and is reversible.

<Tabs>
  <Tab title="React / Next.js">
    ```tsx theme={null}
    const { client } = useVeltClient();

    client.setUnstyledMode(true);                                    // keep layout styles
    client.setUnstyledMode(true, { keepFunctionalStyles: false });   // strip everything
    client.setUnstyledMode(false);                                   // restore
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```js theme={null}
    Velt.setUnstyledMode(true);
    Velt.setUnstyledMode(true, { keepFunctionalStyles: false });
    Velt.setUnstyledMode(false);
    ```
  </Tab>
</Tabs>

To also drop Velt's global styles (the ones outside its own components), set `globalStyles: false` in your config:

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltProvider apiKey='API_KEY' config={{ globalStyles: false }}>
        {/* Your app content */}
    </VeltProvider>
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```js theme={null}
    Velt.initConfig('API_KEY', { globalStyles: false });
    ```
  </Tab>
</Tabs>

## What CSS can and can't do

| ✅ CSS can                              | ❌ CSS cannot                                     |
| -------------------------------------- | ------------------------------------------------ |
| Recolor everything (light + dark)      | Reorder or restructure the UI                    |
| Change spacing, radius, fonts, shadows | Add or remove UI parts (use a prop or wireframe) |
| Theme to match a brand                 | Insert your own markup between Velt's pieces     |
| Adjust z-index layering                | Change behavior                                  |

Writing `display:none` to remove parts, or wishing you could move a button? You've hit CSS's ceiling: escalate to [wireframes](/ui-customization/layout) to restructure, or [primitives](/ui-customization/primitives) to toggle features.

## Checklist

* [ ] `shadowDom={false}` on components you style with classes.
* [ ] All Velt CSS in **one** stylesheet.
* [ ] Only token names that exist in [`CSS variables`](/ui-customization/reference/css-variables).
* [ ] Dark values under `:root[data-velt-theme="dark"]`.
* [ ] No `display:none` to remove features: toggle them with a prop.