# Web app

Surface. Prototype: previews/AppShell.html

The signed-in web app, composed: canvas-first VisualMap with insets, the Vault, the bottom Composer with recent chat turns, canvas chrome and the Comfort dialog. A reference composition, not an export.


## Features

- VI-001 Visualize this page (toolbar, right-click) · Open in Visualli: N/A (Paste a link into the Composer instead)
- VI-002 Map: bloom, step inside, depth trail: UX ready
- VI-003 Touch: tap to peek, tap again to step inside: N/A (The same map switches to touch automatically on touch screens (interaction="auto"))
- VI-004 SemanticPeek (an idea's summary): UX ready
- VI-005 SemanticAnchor (term definitions): UX ready
- VI-006 Go deeper (facets for an idea or term): UX ready
- VI-007 Map it (inside this map / new Visualli): UX ready
- VI-008 Movable ideas and Reset layout: UX ready
- VI-009 Edit mode (ideas, connectors, groups): UX ready
- VI-010 Sources panel: UX ready
- VI-011 Export: single-page PDF, multi-page PDF, .visualli file (no share link): UX ready
- VI-012 Chat: Composer and receipts: UX ready
- VI-013 Vault (library of Visuallis): UX ready
- VI-014 Comfort & appearance: UX ready
- VI-015 Tips in the chat stack (e.g. "Layout saved. Want to edit the content too?"): UX ready

## Build it

The web app consumes the design system directly from the monorepo.

### Install

Add `design-system` to the root `package.json` `workspaces`, then depend on it by name from the app (npm workspaces link it locally):

```json
{ "dependencies": { "@visualli/design-system": "*" } }
```

Rules for building pages: [Building with the system](../guidelines/building-with-the-system.html) (`design-system/AGENTS.md`).

### Load order

1. `@visualli/design-system/tokens.css` — every color, type, space, radius, shadow and motion token as a CSS custom property, for all eight themes.
2. `@visualli/design-system/bundle.css` — component styles (imports the Google faces).
3. The components: `import { Button, Composer, VisualMap } from '@visualli/design-system/components'`.

### Tailwind

`tailwind.config.js`: `presets: [require('@visualli/design-system/tailwind-preset')]`. The preset *replaces* Tailwind's colors, spacing, radii, shadows, fonts, type sizes, z-index and motion with the tokens (as CSS variables), so `p-5` = `space-5` = 24px, `bg-surface`, `rounded-lg`, `shadow-float`, `font-hand`, `text-body`, and off-system classes like `text-red-500` don't exist. While migrating an existing config, spread `require('@visualli/design-system/tailwind-preset').theme` into `theme.extend` instead.

### Theme and comfort

Set the look on `<html>` before first paint, server-rendered from the saved preference so there is no flash:

```html
<html data-theme="light" data-type="standard" data-motion="full" data-reveal="gradual" data-scale="md">
```

`data-theme` is one of `light`, `dark`, `focus-light`, `focus-dark`, `colorsafe-light`, `colorsafe-dark`, `contrast-light`, `contrast-dark`. At runtime, call `applyComfort(choice)`. See [Comfort modes](../guidelines/comfort-modes.html).

### Layout

The whole window is the canvas: Vault left, Composer bottom-center, canvas controls top-right, depth trail top-left. See [Surfaces](../guidelines/surfaces.html).