> ## 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. # How Velt customization works > Understand how Velt customization layers work together and when to use CSS, wireframes, primitives, or headless hooks. Read this once. It gives you the mental model that makes everything else obvious. *** ## What Velt is Velt is a set of **collaboration features** that you drop into your app: comments, a comments sidebar, notifications, reactions, presence, live cursors, huddles, and recordings. Velt handles the hard parts, including storing comments, real-time sync between users, mentions, permissions, and threading. You decide how it **looks**. ## The mental model: behavior vs. presentation > **Velt owns behavior + data + real-time sync. You own presentation.** * **Behavior / data / sync** (Velt's job): saving a comment, syncing it to other users live, resolving a thread, @mentions, reactions, who's online, unread counts. You never re-implement these. * **Presentation** (your job, to whatever degree you want): colors, spacing, fonts, layout, which pieces show, the surrounding HTML, icons. Customization is simply **choosing how much of the presentation you take over.** That's the only decision. The four "layers" below are four answers to it. ## The four layers Reach for them in this order: **CSS → Wireframes → Primitives → Headless**: escalating only when the cheaper layer can't express your design. ``` less work / Velt does more more work / you do more ───────────────────────────────────────────────────────────────────────────────▶ CSS Wireframes Primitives Headless (recolor it) (your layout, (you compose the (you build the Velt wires the building blocks: entire UI from data & behavior) loop, conditionals, hooks) props: + any UI lib) ``` > **Why wireframes are *less* effort than primitives:** with wireframes, Velt fetches the data, loops the threads, and wires each slot's behavior; you just supply layout markup. With primitives, *you* write that code yourself, and in exchange get full control and your own UI library. | Layer | You provide | Velt provides | Use when | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **CSS** | Colors, spacing, fonts (CSS variables + class overrides with `!important`) | The whole UI, structure, and behavior | The design is Velt's default look with different colors/spacing/typography. **Always available, layered on every other approach.** | | **Wireframes** | The **HTML layout** for each slot (header, thread card, composer…) | The behavior **and the data/looping** wired into each named slot you fill | The design changes the **structure/layout** of Velt's UI but the features stay the same, and you don't need your own interactive components inside it. **The default for structural customization.** | | **Primitives** | The composition yourself: fetch data, loop, conditionals, pass props; arrange the building-block components (and their sub-components) anywhere; optionally wrap in your UI library | Ready-made building-block components (`VeltCommentDialog`, `VeltComments`, and a sub-component for nearly every child) with default design + full behavior | You need **full control**, your **own UI component library**, your **own interactivity**, to place Velt pieces **anywhere** in your tree, or to customize a piece more deeply than its wireframe allows. | | **Headless** | **The entire UI** | Data + actions through React hooks (`useCommentAnnotations`, `useAddComment`, …) | Last resort: the design is so custom (or so tied to your own components, or on a surface Velt can't draw) that nothing above fits. | One more wireframe superpower: **variants** let you register several looks for the same component and switch between them (e.g. a compact card in the sidebar, a full card in the dialog); see [Variants](/ui-customization/wireframes/layout-customization#variants). Detailed walkthroughs: [`CSS`](/ui-customization/styling) · [`Wireframes`](/ui-customization/layout) · [`Primitives`](/ui-customization/primitives) · [`Headless`](/ui-customization/headless). ## Mix layers per feature The layers are **not** an app-wide setting. You pick one **per feature/surface**, and you can even combine them on the same surface: wireframe the comment dialog while the sidebar stays a plain primitive, or drop in a `VeltCommentDialog` primitive *and* wireframe parts of that same dialog. How to combine them safely: [`Combining approaches`](/ui-customization/combining-approaches). ## Wireframes are copies; primitives are components This is the most important non-obvious fact in the whole guide. * **Primitives are real components.** `VeltCommentDialog` is a normal React component that renders a `` element. Wrap it in a MUI ``, a shadcn ``, anything: your library's components keep working normally next to it. * **Wireframes are cloned markup.** Velt **copies** your slot markup into its own render tree. Any interactivity you attached (a React `onClick`, `useState`, a stateful library component) **does not run** in the copy. Inside a wireframe, behavior comes only from Velt's own slot components; your markup is the visual shell, and CSS classes are fine. Primitives also give **deep layout control**: there's a sub-component for nearly every child, so you can restructure as deeply as the component tree goes. The one limit: *leaf* pieces (no children) are customized with that leaf's **wireframe**, even inside an otherwise-primitive build. Which of the two your design needs is a decision, not a concept: the [decision tree](/ui-customization/decision-tree#the-ui-component-library-question-dont-miss-this) has the full table. Why the copy behaves this way: [`Edge cases and limitations`](/ui-customization/edge-cases-and-limitations). ## Shadow DOM Velt can render its UI inside a **shadow DOM**: an isolated bubble your global stylesheets cannot reach. It keeps Velt's styles from clashing with your app, and it decides whether your CSS lands: * ✅ **CSS variables** (`--velt-*`) cross the boundary, so theming always works. * ❌ **Class and element selectors** do not: those need `shadowDom={false}` (or `injectCustomCss`). Choose your strategy in [`Setup`](/ui-customization/setup); full detail in [`CSS`](/ui-customization/styling). ## Where to go next Start with the **[`Decision tree`](/ui-customization/decision-tree)** to pick the right layer or layer mix for your specific design. This is the spine of the guide; start every new design there. Working from a Figma file? The [UI Customization Plugin](/get-started/ui-customization-plugin) can run the decision for you and build a verified result (comments + notifications).