> For the complete documentation index, see [llms.txt](https://voyzu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://voyzu.gitbook.io/docs/extending-voyzu/theming.md).

# Theming

Voyzu can be rebranded without changing individual module pages. A theme is made up of:

* The application logo and brand name.
* Public `--voyzu-*` CSS design tokens.
* The fonts loaded by the web application.

Shared components and page styles consume these public tokens, so a global override flows through navigation, forms, tables, detail pages, reports, and feedback states.

Voyzu currently applies one theme to the deployed application through the CSS cascade. It does not provide a runtime theme provider or a built-in per-user theme switcher.

## Design token layers

The public theme contract is defined in `packages/@voyzu/ui-style/src/css/design-tokens.css`. Its tokens cover the main visual concerns:

* Brand and primary interaction colors.
* Application backgrounds, surfaces, borders, and text.
* Success, warning, danger, information, and neutral states.
* Typography, spacing, control sizing, and border radii.
* Shadows, scrollbars, and motion.

Variables beginning with `--voyzu-` are intended for application and component use. Variables beginning with `--_`, `--wa-`, or `--tw-` are implementation primitives; do not use or override them in an application theme.

Prefer changing public semantic tokens instead of overriding component selectors. For example, change the brand, surface, or danger tokens rather than setting colors separately on buttons, alerts, and badges.

## Apply a theme

Create an application stylesheet such as `apps/web/app/theme.css` and override the public tokens at `:root`:

```css
:root {
  --voyzu-color-brand: #006c67;
  --voyzu-color-brand-hover: #005752;
  --voyzu-color-brand-soft: #d9f0ee;
  --voyzu-color-brand-subtle: #eff9f8;

  --voyzu-color-background: #f6f8f8;
  --voyzu-color-link: #006c67;
  --voyzu-color-link-hover: #004f4b;

  --voyzu-font-family: "Source Sans 3", sans-serif;
  --voyzu-font-family-heading: "Source Sans 3", sans-serif;
  --voyzu-font-family-nav: "Source Sans 3", sans-serif;
}
```

Import the theme after the default design tokens in `apps/web/app/(web)/layout.tsx`:

```ts
import "@voyzu/ui-style/css/design-tokens.css";
import "../theme.css";
```

Import order is significant: the application theme must come after `design-tokens.css` so its values win the cascade.

Keep related token states together. When changing the brand color, also review its hover, soft, subtle, focus, link, and text variants. When changing semantic feedback colors, verify the corresponding background, text, border, and hover values as a set.

## Change the logo

The default logo is served from:

```
apps/web/public/voyzu/voyzu_color_logo_transparent.png
```

Replacing that file while keeping the same path updates the top navigation and mobile navigation without further code changes. Use a transparent raster image with enough contrast at the compact navigation size.

To use a different path or render a custom brand component, update `VoyzuBrand` in `apps/web/app/(web)/surface/top-nav/VoyzuBrand.tsx`. Also update the `logoSrc` passed to the Finance, Organization, and Settings mobile navigation components. Keep the image alternative text aligned with the displayed brand.

## Change fonts

Font-family tokens only select a font; the font must also be available to the browser. The default Inter and Manrope web fonts are loaded in `apps/web/app/(web)/layout.tsx`.

When changing fonts, update the font loading in that layout and then override the body, heading, and navigation font-family tokens. Check page titles, dense tables, form controls, navigation labels, and narrow mobile layouts because different font metrics can change wrapping and control height.

## Deeper changes

If the existing public tokens do not describe a required semantic role, add a new `--voyzu-*` token to `design-tokens.css` and consume it from shared styles or components. This keeps the theme contract explicit and prevents raw brand values from spreading through module CSS.

Changes to component structure, page layouts, breakpoints, or interaction behavior are UI customizations rather than theme changes. Keep those changes in the relevant `@voyzu/ui-components`, `@voyzu/ui-layout`, or application surface code.

## Inspect and verify

Run the local UI Reference application to inspect components and the current design-token values:

```shellscript
npm run dev:ui-reference
```

Open `http://localhost:3001`, then select **CSS Variables**. The color reference is available directly at `http://localhost:3001/css-variables/colors`.

After applying a theme, review representative list, detail, form, modal, report, and navigation screens. Check desktop and mobile layouts, focus and hover states, disabled controls, semantic feedback colors, text contrast, and logo legibility. The theme should preserve the meaning of success, warning, danger, and information states even when their palette changes.

<figure><img src="/files/6fliCKD9mdTmHOaZiBWU" alt="Voyzu UI Reference color variable page"><figcaption><p><a href="http://localhost:3001/css-variables/colors">UI Reference color variables</a></p></figcaption></figure>