---
title: UI & Theming Engine
description: Exploration of VertiWiki's responsive UI shell, modular layout modes, and dynamic CSS token theme engine.
tags: [vertiwiki, ui, theming, design-tokens, layout-modes, css]
---

# UI & Theming Engine

> For the complete documentation index and agent navigation, see [llms.txt](/llms.txt).

VertiWiki features a decoupled user interface architecture built entirely with modern vanilla TypeScript, CSS Grid, Flexbox, and CSS Custom Properties. It achieves rich responsiveness, dark/light adaptation, and multi-layout modes with zero reliance on heavy UI frameworks like React or Vue.

---

## 🖥️ Layout Shell Architecture (`src/ui/layout.ts`)

The root application mounts inside `#verti-app` and renders the following core landmark areas:

```text
+-------------------------------------------------------------------------+
| .verti-header (Logo, Title, Search Bar, Theme Switcher, Lang Switcher)  |
+------------------------------------+------------------------------------+
| .verti-sidebar (Navigation Tree)   | .verti-main-container              |
|                                    |   .verti-breadcrumbs               |
|                                    |   .verti-article (Markdown Content)|
|                                    |   .verti-prev-next (Pagination)    |
|                                    |   .verti-footer                    |
+------------------------------------+------------------------------------+
|                                    | .verti-toc-sidebar (On this page)  |
+------------------------------------+------------------------------------+
```

### Modular Layout Modes (`data-layout`)
VertiWiki supports multiple layout modes configured globally via `config.json` (`"layoutMode": "..."`) or overridden on individual pages via YAML frontmatter (`layout: book`):

| Layout Mode | Intended Audience | Visual Behavior |
| :--- | :--- | :--- |
| `default` | Standard documentation & wikis | Classic 3-column layout (Sidebar + Article + TOC) |
| `book` | Long-form reading & digital books | Centered prose, discreet navigation, page-turner focus |
| `handbook` | Company policies, SOPs, HR manuals | Pastel callouts, checklist styling, card highlights |
| `api` | Developer API references | Split-column layout (Prose on left, Code/cURL on right) |
| `hub` | Enterprise portals & team indexes | Grid layout with card sections and wide hero banner |

### Reading Ergonomics (`contentWidth`)
To optimize readability for non-technical audiences:
- `normal`: Standard documentation width (800px–900px).
- `readable`: Enforces optimal typographic measure (68ch line-length, 1.8 line-height).
- `full`: Unrestricted width, ideal for wide data tables and complex architecture diagrams.

---

## 🎨 Theme Engine & Design Tokens (`src/ui/theme.ts`)

Visual styling is governed by design tokens mapped to CSS Custom Properties under the `--verti-*` namespace:

```css
:root {
  --verti-bg-base: #ffffff;
  --verti-text-primary: #0f172a;
  --verti-text-secondary: #475569;
  --verti-border: #e2e8f0;
  --verti-primary: #2563eb;
  --verti-primary-fg: #ffffff;
  --verti-code-bg: #f8fafc;
  --verti-radius: 8px;
}
```

### Theme Presets & External JSON Files
Themes can be bundled internally or defined as standalone JSON files in `themes/` (e.g. `themes/obsidian.json`, `themes/dracula.json`, `themes/nord.json`):

```json
{
  "id": "dracula",
  "name": "Dracula",
  "previewColor": "#bd93f9",
  "light": {
    "background": "#f8f8f2",
    "foreground": "#282a36",
    "primary": "#bd93f9",
    "border": "#e2e8f0"
  },
  "dark": {
    "background": "#282a36",
    "foreground": "#f8f8f2",
    "primary": "#bd93f9",
    "border": "#44475a"
  }
}
```

### Theme Inheritance (`extends`)
A custom theme can extend an existing preset, overriding only specific tokens:
```json
{
  "id": "my-brand",
  "extends": "default",
  "dark": {
    "primary": "#10b981"
  }
}
```

---

## 🌐 Dynamic UI Controls

### Table of Contents (`src/ui/toc.ts`)
The TOC engine automatically scans rendered `h2` and `h3` tags, extracts clean titles, and binds an `IntersectionObserver` to highlight the active section as the reader scrolls.

### Language Chooser (`src/ui/language-chooser.ts`)
When two or more locales are declared in `config.json`, a globe icon appears in the top navigation bar. Clicking it opens a dropdown allowing readers to switch languages with a single click.

---

## 🔗 Next Steps

- Explore the plugin system in [Plugins & Extensions](plugins-and-extensions.md).
- View runtime schema properties in [Configuration Overview](../configuration/overview.md).
- Learn how to create custom themes in [Local Development](../guides/development.md).