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

# Setup

> Set up the project structure, shadow DOM strategy, and customization files needed before changing Velt UI.

Set up your project for UI customization: install Velt, make sure your CSS can reach it, and organize your customization code.

## 1. Install Velt

Customization starts from a **working Velt installation**: SDK installed, user authenticated, document set, and Velt's default UI (comments, sidebar, …) rendering in your app.

Not there yet? Follow the [Quickstart](https://velt.dev/docs/get-started/quickstart.md) (or use the [Installation Plugin](https://velt.dev/docs/get-started/installation-plugin.md)), then come back.

> [!TIP]
>
> Get Velt's **default** UI showing first, unstyled. Confirm comments work. *Then* customize. If you build custom UI against a Velt that isn't initialized, you can't tell setup bugs from styling bugs.

## 2. Recommended: use the UI Customization Plugin

If your design is in **Figma** and you use **Cursor or Claude Code**, install the [UI Customization Plugin](https://velt.dev/docs/get-started/ui-customization-plugin.md): it picks the approach, builds the customization in your app, and verifies the result against your design in a real browser (comments and notifications today).

If your design isn't in Figma, or you prefer building by hand, continue with the manual steps below.

## 3. Choose your shadow DOM strategy

Velt can render inside a **shadow DOM** (an isolated DOM bubble). That isolation blocks your stylesheets, so decide up front how your CSS reaches Velt:

* **Variable-only theming** (you only override `--velt-*` tokens): works **regardless** of shadow DOM; variables cross the boundary. Nothing to change.
* **Selector-based CSS** (class/element selectors) **or styled wireframes**: these **cannot** reach inside the shadow DOM. Pick one of two supported options:

**Option A: turn shadow DOM off** so your normal stylesheet reaches the elements:

> [tab] React / Next.js
>
> ```tsx theme={null}
> <VeltComments shadowDom={false} />
> <VeltCommentsSidebar shadowDom={false} />
> ```

> [tab] Other Frameworks
>
> ```html theme={null}
> <velt-comments shadow-dom="false"></velt-comments>
> <velt-comments-sidebar shadow-dom="false"></velt-comments-sidebar>
> ```

**Option B: keep shadow DOM on and inject your CSS into the shadow root** (keeps Velt's style isolation):

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

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

If you do neither, your `--velt-*` overrides still apply but your class-based CSS won't reach inside, so it looks like "my CSS does nothing."

**Rule of thumb:** anything beyond pure variable theming ⇒ shadow DOM off **or** `injectCustomCss`. (Details: [`CSS`](https://velt.dev/docs/ui-customization/styling).)

## 4. Set up the folder structure

This structure keeps **your app code**, **Velt setup**, and **Velt UI customization** cleanly separated. Use it as-is.

```text theme={null}
components/
├── Header.tsx, Body.tsx, …          ← your normal app UI (no Velt customization here)
└── velt/                            ← ALL Velt-related code lives here
    ├── VeltCollaboration.tsx        Mounts Velt components + global config
    ├── VeltInitializeUser.tsx       Identify the user
    ├── VeltInitializeDocument.tsx   Set the document(s)
    └── ui-customization/            ← ALL customization lives here
        ├── VeltCustomization.tsx    The single <VeltWireframe> root (if wireframing)
        ├── VeltCommentDialogWf.tsx  One file per customized surface
        ├── VeltCommentSidebarWf.tsx
        ├── ThreadCardWf.tsx
        └── styles.css               ONE stylesheet for all Velt CSS
```

Why this works:

* **One place to look.** Anyone (or any tool) finds all customization under `components/velt/ui-customization/`.
* **App UI stays separate** from Velt UI: no tangling.
* **One stylesheet** for all Velt CSS variables/classes, not scattered across components.
* **One `<VeltWireframe>` root** (in `VeltCustomization.tsx`): easy to find.

> [!NOTE]
>
> **Keep exactly one `<VeltWireframe>` in the whole app.** It feeds a global registry; extra roots merge first-with-content-wins, which is order-dependent and conflict-prone. `VeltCustomization.tsx` is its one home.

> [!TIP]
>
> For **CSS-only** or **primitives-only** customization you may not need a `ui-customization/` folder at all: a single `velt.css` + the components in `VeltCollaboration.tsx` is enough. Adopt the full structure when you start wireframing.

## 5. Build your customization

Open the page for your chosen approach: [`CSS`](https://velt.dev/docs/ui-customization/styling), [`Wireframes`](https://velt.dev/docs/ui-customization/layout), [`Primitives`](https://velt.dev/docs/ui-customization/primitives), or [`Headless`](https://velt.dev/docs/ui-customization/headless). Mixing layers on one surface? See [`Combining approaches`](https://velt.dev/docs/ui-customization/combining-approaches).

> [!NOTE]
>
> As you build, handle accessibility, i18n, RTL, responsive behavior, and testing alongside each surface, not at the end: see [`Accessibility & localization`](https://velt.dev/docs/ui-customization/accessibility-and-localization).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.