> ## Documentation Index
> Fetch the complete documentation index at: https://velt-codex-ui-customization-guide-refresh.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>

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                                                                                                                                  | Design control              | Effort      |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ----------- |
| **CSS**        | Change colors/spacing/fonts via CSS variables (+ class overrides with `!important`)                                                          | Theme only                  | Lowest      |
| **Wireframes** | Keep Velt's behavior/data-wiring but supply your own HTML layout for each slot                                                               | High (layout/structure)     | Low         |
| **Primitives** | Compose Velt's building-block components yourself (you do the looping, conditionals, prop-passing): full control + works with any UI library | Highest (short of headless) | Medium-High |
| **Headless**   | Velt gives you data + actions via hooks; you build 100% of the UI                                                                            | Total                       | Highest     |

**Default preference: wireframes.** Use CSS for pure theming, **wireframes** for custom structure (the usual choice), **primitives** when you need full control / your own UI component library / your own interactivity (or to customize a *leaf* piece), and **headless** only as a last resort.

You can **mix them: even on the same surface** (e.g. drop in a `VeltCommentDialog` primitive *and* wireframe parts of it; or wireframe the dialog, primitive sidebar, CSS on both). See [`Combining approaches`](/ui-customization/combining-approaches).

***

## How to use this guide

Read in this order. Don't skip the first three: they prevent 90% of mistakes.

1. **[`How Velt customization works`](/ui-customization/how-it-works)**: the mental model + how the layers relate. *(5 min)*
2. **[`Decision tree`](/ui-customization/decision-tree)**: **start here for any new design.** Pick the right layer(s) for what you're building. *(the spine of this guide)*
3. **[`Setup`](/ui-customization/setup)**: prerequisites, the `shadowDom` rule, and the folder structure to put your code in.
4. **[`Build methodology`](/ui-customization/build-methodology)**: **HOW to build:** the **extract → map → build → measure** pipeline. Extract the exact numbers + icon SVGs deterministically (**[`Extraction`](/ui-customization/extraction)**), map each element to a real slot/prop/icon (Velt Code Connect, **[`Manifest`](/ui-customization/reference/manifest)**: props-first, supply every slot), build in small patches applying the exact numbers, then **measure** (delta table, not eyeballing). Pair with **[`Build gotchas`](/ui-customization/build-gotchas)** (the traps + the fix).
5. **The approach you picked**: open the matching approach page from the UI Customization navigation.
6. **The feature you're customizing**: comments are covered throughout the approach guides; to resolve a specific comment **surface** (dialog, sidebar V1/V2, sidebar button, pin, bubble, comment tool) to its primitive · root wireframe · key props · flags · variables, use the **Surface lookup** map in [`Component catalog`](/ui-customization/reference/component-catalog). For any other feature (notifications, reactions, recorder, mentions, presence/cursors, activity log, …) open the matching feature guide, starting with [`Other features`](/ui-customization/features/other-features).
7. **Does the design need a component that isn't showing?** Check [`Feature flags`](/ui-customization/reference/feature-flags): many features (reply avatars, priority, minimap, @here, …) are **off by default** and just need a prop.
8. **[`Reference`](/ui-customization/reference/component-catalog)**: the dictionary: look up exact CSS variables, classes, wireframe slots/tokens, props, **behaviors** ([`Behaviors`](/ui-customization/reference/behaviors)), **data fields/events** ([`Data models`](/ui-customization/reference/data-models)), and hooks while you build. You *look things up* here: you don't read it cover to cover.
9. **[`Rules`](/ui-customization/rules)**: the non-negotiables. Read once; re-check before you ship.
10. **[`Verifying a customization`](/ui-customization/verifying-a-customization)**: after each surface, confirm it matches the design, behavior is intact, and the rules pass. The definition of "done".

When stuck: **[`Debugging`](/ui-customization/debugging)** (symptom → fix), **[`SDK gaps and blockers`](/ui-customization/sdk-gaps-and-blockers)** (fixable problem vs. real SDK gap, and how to record a gap honestly), **[`Patterns and tips`](/ui-customization/patterns-and-tips)** (proven recipes), **[`Context`](/ui-customization/context)** (attach/read your own data on comments), **[`Cross-cutting concerns`](/ui-customization/localisation)** (a11y/i18n/RTL/responsive/testing), and **[`Edge cases and limitations`](/ui-customization/edge-cases-and-limitations)**.

***

## Docs map

Use these public routes when you share or link to this guide:

| Area           | Pages                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Concepts       | [`How it works`](/ui-customization/how-it-works), [`Decision tree`](/ui-customization/decision-tree), [`Setup`](/ui-customization/setup)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Build workflow | [`Build methodology`](/ui-customization/build-methodology), [`Extraction`](/ui-customization/extraction), [`Build gotchas`](/ui-customization/build-gotchas)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Approaches     | [`CSS`](/ui-customization/styling), [`Wireframes`](/ui-customization/layout), [`Primitives`](/ui-customization/primitives), [`Headless`](/ui-customization/headless), [`Combining approaches`](/ui-customization/combining-approaches)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Feature guides | [`Comment surfaces`](/ui-customization/features/comment-surfaces), [`Notifications`](/ui-customization/features/notifications), [`Reactions`](/ui-customization/features/reactions), [`Recorder and transcription`](/ui-customization/features/recorder-and-transcription), [`Mentions and autocomplete`](/ui-customization/features/mentions-and-autocomplete), [`Presence and cursors`](/ui-customization/features/presence-and-cursors), [`Activity log`](/ui-customization/features/activity-log), [`Annotations, tags, arrows, and areas`](/ui-customization/features/annotations-tags-arrows-areas), [`Other features`](/ui-customization/features/other-features)                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Guidance       | [`Rules`](/ui-customization/rules), [`Verifying a customization`](/ui-customization/verifying-a-customization), [`Patterns and tips`](/ui-customization/patterns-and-tips), [`Context`](/ui-customization/context), [`Cross-cutting concerns`](/ui-customization/localisation), [`Debugging`](/ui-customization/debugging), [`Edge cases and limitations`](/ui-customization/edge-cases-and-limitations), [`SDK gaps and blockers`](/ui-customization/sdk-gaps-and-blockers)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Reference      | [`Component definitions`](/ui-customization/reference/component-definitions), [`Component catalog`](/ui-customization/reference/component-catalog), [`Feature flags`](/ui-customization/reference/feature-flags), [`Component config`](/ui-customization/reference/component-config), [`Props`](/ui-customization/reference/props), [`APIs`](/ui-customization/reference/apis), [`Events`](/ui-customization/reference/events), [`Hooks`](/ui-customization/reference/hooks), [`Data models`](/ui-customization/reference/data-models), [`Primitives`](/ui-customization/reference/primitives), [`Wireframe components`](/ui-customization/reference/wireframe-components), [`Wireframe tokens`](/ui-customization/conditional-templates), [`Wireframe variables`](/ui-customization/template-variables), [`CSS variables`](/ui-customization/reference/css-variables), [`CSS classes`](/ui-customization/reference/css-classes), [`Behaviors`](/ui-customization/reference/behaviors), [`Manifest`](/ui-customization/reference/manifest), [`Source-of-truth invariant`](/ui-customization/reference/source-of-truth-invariant) |

***

## Implementation checklist

0. **Recognize first: map the design to Velt components.** Before using the decision tree, identify which Velt component each design element represents, whether it is available, and what needs to be enabled. Use [`Component definitions`](/ui-customization/reference/component-definitions) for design intent, visual cues, positioning cues, look-alikes, and off-by-default flags. When two components match, confirm the intended component. When nothing matches, treat it as host UI or an SDK gap; do not force a Velt mapping.
1. **Run the decision tree** ([`Decision tree`](/ui-customization/decision-tree)) against each recognized surface. It returns the right layer, or per-feature mix, with the reason.
2. **Treat [`Rules`](/ui-customization/rules) as hard constraints.** They cover the core invariants: one `<VeltWireframe>` per app, `shadowDom={false}` when styling with selectors, no interactive React inside a wireframe, and no brittle DOM or timing workarounds.
3. **Use only real identifiers.** The [`Reference`](/ui-customization/reference/component-catalog) pages are the source of truth for CSS variables, classes, wireframe slots, primitives, variables, props, config, feature flags, hooks, and component definitions. If a name is not documented there, do not use it unless you have verified it against the live SDK and added it back to the reference.
4. **Follow each approach page in order.** The CSS, wireframes, primitives, headless, and combining approaches pages are written as step-ordered guides.
5. **Match the folder structure in [`Setup`](/ui-customization/setup).** This keeps Velt setup, customization, assets, and host app UI separated.
6. **Verify each surface before moving on** ([`Verifying a customization`](/ui-customization/verifying-a-customization)). Drive its states, confirm Velt behavior is intact, run the static rules scan, and record a PASS, PARTIAL, FAIL, or BLOCKED verdict. Work one surface at a time.
7. **When a goal seems impossible, run the gap flow** ([`SDK gaps and blockers`](/ui-customization/sdk-gaps-and-blockers)). Rule out fixable causes such as shadow DOM, specificity, wrong layer, off-by-default features, and custom data before recording a real SDK gap.