> ## 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.

# 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.

<Steps titleSize="h2">
  <Step title="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](/get-started/quickstart) (or use the [Installation Plugin](/get-started/installation-plugin)), 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.
    </Tip>
  </Step>

  <Step title="Recommended: use the UI Customization Plugin">
    If your design is in **Figma** and you use **Cursor or Claude Code**, install the [UI Customization Plugin](/get-started/ui-customization-plugin): 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.
  </Step>

  <Step title="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:

    <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 shadow DOM on and inject your CSS into the shadow root** (keeps Velt's style isolation):

    <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>

    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`](/ui-customization/styling).)
  </Step>

  <Step title="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.
    </Note>

    <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.
    </Tip>
  </Step>

  <Step title="Build your customization">
    Open the page for your chosen approach: [`CSS`](/ui-customization/styling), [`Wireframes`](/ui-customization/layout), [`Primitives`](/ui-customization/primitives), or [`Headless`](/ui-customization/headless). Mixing layers on one surface? See [`Combining approaches`](/ui-customization/combining-approaches).

    <Note>
      As you build, handle accessibility, i18n, RTL, responsive behavior, and testing alongside each surface, not at the end: see [`Cross-cutting concerns`](/ui-customization/localisation).
    </Note>
  </Step>
</Steps>