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

# Velt UI Customization Guide

> Learn the Velt UI customization model, reading order, and workflow for matching Velt collaboration UI to your design.

<Info>
  Everything you need to make Velt's collaboration UI (comments, sidebar, notifications, reactions, presence, and more) match **your** design: from changing a color to building a 100% custom UI.
</Info>

<CardGroup cols={3}>
  <Card title="UI Customization Plugin" icon="palette" href="/get-started/ui-customization-plugin">
    Turn a Figma design into verified Velt UI customization (comments + notifications) in Cursor or Claude Code.
  </Card>

  <Card title="Storybook" icon="book-open" href="https://storybook.velt.dev/">
    Explore Velt components and primitives interactively: states, props, and layouts in a live playground.
  </Card>

  <Card title="Theme Playground" icon="paintbrush" href="https://playground.velt.dev/themes">
    Visually customize Velt themes and copy the generated CSS variables.
  </Card>
</CardGroup>

This guide explains the customization model from first principles, then gives you a repeatable workflow for turning a design, such as a Figma file, into a working Velt implementation.

It covers **UI customization only**. It does *not* cover auth, permissions, data providers, or self-hosting, except the one setup flag (`shadowDom`) that customization depends on.

***

## The one idea to remember

**Velt owns the behavior, data, and real-time sync. You own the presentation.**

Every customization approach in this guide is just a different amount of "you own the presentation": from *recolor it* to *rebuild it from scratch*.

***

## The four layers (in 10 seconds)

Ordered by how you should reach for them: **CSS → Wireframes → Primitives → Headless**:

| Layer          | What you do                                                                |
| -------------- | -------------------------------------------------------------------------- |
| **CSS**        | Change colors, spacing, and fonts with CSS variables                       |
| **Wireframes** | Keep Velt's behavior and data wiring; supply your own HTML layout per slot |
| **Primitives** | Compose Velt's building-block components yourself, inside any UI library   |
| **Headless**   | Take data and actions from hooks and build 100% of the UI                  |

**Default preference: wireframes** for structural changes, and you can mix layers freely, even on the same surface. [`How it works`](/ui-customization/how-it-works) teaches the model; [`Combining approaches`](/ui-customization/combining-approaches) covers mixing.

***

## How to use this guide

Read in this order:

1. **[`How it works`](/ui-customization/how-it-works)**: the mental model. *(5 min)*
2. **[`Decision tree`](/ui-customization/decision-tree)**: pick the right approach for your design.
3. **[`Setup`](/ui-customization/setup)**: prerequisites, the `shadowDom` rule, and where to put your code.
4. **The approach you picked**: open its page under **Approaches** in the sidebar.
5. **The feature you're customizing**: comments run through the approach guides; every other feature area under **Components** opens with an overview page ([`Customize by feature`](/ui-customization/features/other-features) is the index). A piece not showing? It may be [off by default](/ui-customization/reference/feature-flags).
6. **[`Reference`](/ui-customization/reference/component-catalog)**: look up exact names (variables, classes, slots, props, hooks) while you build. If a name isn't there, it doesn't exist: don't guess.

Design already in Figma? You can skip the manual workflow: the [UI Customization Plugin](/get-started/ui-customization-plugin) runs this whole loop (pick approach → build → verify) for you.