# Brand book

Visualli turns anything people bring — a PDF, a link, a video, a thought — into a **visual map they can walk into**. The design system serves one promise: *understand anything visually*. Visuals are the stage; text is the stagehand.

Feel: **joyful · spatial · visual · gradual reveal · fresh.** Never: generic SaaS, generic "AI startup" (no blue-to-purple gradients, no sparkle-everything, no glassy cards), never a wall of text.

## Content fundamentals

- **Voice is precise; visuals are playful.** Copy says exactly what happened in as few words as possible ("Added 3 ideas under Sleep"), the canvas carries the delight.
- **Sentence case** everywhere in the interface and in headlines. Capitals only in the `display` face (Haksen is caps-only), which is reserved for eyebrows, deck titles and empty states.
- **Short declaratives that end in a period** are the house headline: "Bring anything." "Hop on." "Understand anything Visually."
- **You / we.** Speak to the learner as *you*; Visualli is *we* only on marketing surfaces. In the product, Visualli never says "I".
- **American spelling** (color, center, memorize).
- **Vocabulary** — use these words, consistently:
  | Say | Meaning | Avoid |
  | --- | --- | --- |
  | a **Visualli** (plural **Visuallis**) | one map the user made | "diagram", "mind map", "board" |
  | the **vault** | the user's library of Visuallis | "files", "workspace" |
  | **node** / **idea** | one concept on the map ("idea" in UI copy, "node" in docs and code) | "bubble", "card" |
  | **connector** | a labelled arrow between two ideas | "edge" in UI copy |
  | **layer**, **level** | what opens inside an idea; level 0 is the overview | "page", "child map" |
  | **rings** | the outlines around an idea that has layers inside | "badge", "indicator" |
  | **step inside** / **back out** | entering and leaving an idea's inner layer (its rings) | "expand", "collapse", "drill down" |
  | **go deeper** | understanding one idea or term in depth (the facets panel) | "learn more" (reserved for external links), "details" |
  | **peek** | an idea's summary on hover or first tap | "tooltip", "popup" |
  | **map it** | turn a topic into a map — inside this one or as a new Visualli | "create", "generate" |
  | **bring** | adding a source | "upload" (except for the literal file picker) |
- **Emoji**: allowed in marketing and social copy, one per message at most, never in product UI chrome. ✨ is not a stand-in for "AI".
- **AI is invisible plumbing.** Say what Visualli did ("Mapped 6 ideas from memory-notes.pdf"), not that "AI generated" it.
- **™**: write *Visualli™* once — on first mention in legal footers, the website footer, decks' title slide and press material. Never in product UI, never in headlines.
- Numbers as numerals ("6 ideas", "3 layers"); time as relative in the vault ("2m", "Tue", "Sep 12").

## Visual foundations

### Color — three families, three jobs
1. **Spectrum** (`spectrum-teal`, `spectrum-harbor`, `spectrum-iris`, `spectrum-berry`, `spectrum-coral`, `spectrum-amber`, `spectrum-sun`, `spectrum-stone`, plus `root-ink`) — the logo's exact letter colors. Brand moments only: the wordmark, `SpectrumBar`, marketing blocks, the `Signature` swash. Never as a UI fill behind text, never blended into a gradient. The **SpectrumBar replaces the old blue→pink gradient**: colors side by side, each one whole.
2. **Topics** (`topic-<name>` + `topic-<name>-ring`, eight of them) — pastel fills derived from the spectrum, for nodes and anything that echoes a node (vault dots, avatars, roadmap votes). Topic colors **separate siblings; they never carry meaning.** Labels on them always use `node-ink` (10:1 or better). They stay pastel in dark mode — ideas glow on the dark canvas.
3. **Interface neutrals** — `canvas`, `surface`, `surface-sunken`, `surface-overlay`, `line`, `line-strong`, `ink`, `ink-muted`, `ink-subtle`, plus `action`/`on-action`, `focus`, `link` and the four statuses. Chrome is quiet so the map can be loud.

Rules: one `action` per view (Send, New Visualli, Join early access). `action` is root-ink in light and paper in dark — there is no brand-blue button. Status colors always travel with an icon and a word. Every text token's usage note names the grounds it passes on; all pairs are checked at 4.5:1 (7:1 in the high-contrast themes) across all eight themes.

### Type — four voices
| Family | Face | Use |
| --- | --- | --- |
| `display` | **Haksen** (caps only, the wordmark's geometry) | `eyebrow`, `display-*`: kickers, deck titles, empty states, vault group labels |
| `ui` | **Atkinson Hyperlegible Next** | everything you read and operate: `title-l` … `caption` |
| `hand` | **Kalam** | the canvas: `node-root`, `node-label`; the one `signature` word per screen ("Understand anything *Visually*."); up to three hand-set key words in a marketing lede |
| `note` | **Caveat** | `edge-label` on connectors, `annotation` marginalia ("tap the rings to step inside ↓") |
| `mono` | Atkinson Hyperlegible Mono | `code`: the .visualli JSON, spec docs |

Atkinson Hyperlegible was drawn for low-vision readers; choosing it says *inclusive* before a word is read. Hand faces live on the canvas and in marketing — never in buttons, inputs or menus. In **Readable type** mode all hand faces fall back to `ui`.

### Space, radius, elevation
- 4px rhythm: `space-1` (4) … `space-9` (96). Floating chrome sits `space-4` from the window edge on desktop, `space-3` on mobile.
- Radii are soft and generous: `radius-sm` (10) for controls, `radius-md` (16) for cards and menus, `radius-lg` (24) for the Composer, Vault and dialogs, `radius-pill` for send, switches and avatars. Nodes have no radius — they are blobs (see *Canvas language*).
- Elevation is two shadows: `shadow-float` (chrome on the canvas) and `shadow-pop` (menus, dialogs, toasts). `shadow-node` lifts nodes — a drop in light, a glow in dark. High-contrast themes drop shadows for 2px borders.

### Layout
One canvas, three floating pieces: the **Vault** on the left (288px, collapsible), the **Composer** bottom-center (max 720px), **canvas controls** top-right. The depth trail sits top-left of the canvas, just right of the Vault. Nothing docks edge-to-edge; everything floats over the map with `space-4` of air, so the canvas always reads as infinite.

### Motion — gradual reveal
The signature move is the **bloom**: when a layer opens, ideas grow out from the center one by one (`duration-reveal` 420ms, `stagger-reveal` 70ms, `ease-bloom` with a small overshoot), then connectors draw themselves in. Drilling in is a camera dive (`duration-zoom` 500ms, `ease-zoom`) into the node you chose; backing out shrinks and fades. UI motion is short and quiet (`duration-quick`, `ease-standard`). Every animation respects *Reduce motion* and `prefers-reduced-motion`: zooms become cross-fades, blooms become a 120ms fade.

### States
Hover lifts (−2px) and turns a node's rings 2°; press settles 1px. Focus is always a solid 2px `focus` ring with 2px offset (on nodes: the outline itself turns `focus`). Disabled is 45% opacity plus a reason nearby. Selected nodes get an `ink` outline.

## Iconography
[Lucide](https://lucide.dev) outline icons (lucide-react 0.344, the set already in the web app): 24px grid, 2px stroke, round caps — 1.75–2.25px at 16px. Use `Icon` with the names in `ICONS`; never mix filled icons in. Icons inherit `currentColor`. The `assets/Icons` group holds the 24 most-used as SVG files (ink `#182140`) for design tools. No emoji in product chrome. There is no "AI" glyph: Visualli's chat receipts carry the **still tree** (`TreeMark`) — the same drawing `ThinkingTree` animates while Visualli works, settled once it's done. Tips (transient hints) carry a check mark.

## Logos
Use the uploaded files in `assets/Logos`, never redraw. `visualli-wordmark-light.png` on light grounds; `visualli-wordmark-dark.png` (badge on near-black) on dark grounds; `visualli-tree-color.png` alone as the app mark at 24px and up; `visualli-tree-mono.png` for single-color print; `visualli-spec-mark.png` only for the open specification. Clear space around the wordmark: the height of the tree disc. The wordmark's letter colors define the spectrum — do not recolor it.

## Don't
- No gradients (the spectrum is shown as whole, adjacent colors).
- No colored left-border cards, no emoji as decoration, no generic stock "AI" imagery.
- No text blocks on the canvas: if a node needs more than three lines, it needs a layer.
- No meaning in topic colors (meaning lives in labels, rings and connector style).
- No hand-drawn faces in controls; no Haksen in sentences.

## Using this system
Load `tokens.css`, then `components/bundle.css` (it imports the Google faces), React 18, then `components/bundle.js` — components are on `window.Visualli`. Set the look on `<html>`: `data-theme` (one of `light`, `dark`, `focus-light`, `focus-dark`, `colorsafe-light`, `colorsafe-dark`, `contrast-light`, `contrast-dark`), plus `data-type`, `data-motion`, `data-reveal`, `data-scale` — or call `Visualli.applyComfort(choice)`. Further sections: **Canvas language** (the open-spec layer), **Comfort modes**, **Surfaces**, **Marketing**, **Migration**.