# DESIGN.md — typst-leaf UI

## Vision

**"A fresh sheet of paper on a warm desk."** Refined editorial-paper aesthetic with a deep teal accent and warm cream neutrals. The app chrome (sidebar, topbar, statusbar) is a warm cream; editor and preview surfaces are a brighter near-white — so reading and writing happen on a sheet of paper that lifts off the desk.

## Brand

- **Name:** typst-leaf — warm, organic, paper-and-ink.
- **Mark:** A teal `Leaf` icon (lucide) beside the wordmark.
- **Personality:** Quiet, considered, a serious editor for prose, papers, and beautiful documents. Like a focused notebook, not a dashboard.

## Palette (Tailwind v4 `@theme`)

Custom tokens in `src/index.css`:

| Token | Value | Use |
|---|---|---|
| `canvas` | `#faf8f4` | App chrome (sidebar, topbar, statusbar, app bg) |
| `surface` | `#fdfdfb` | Editor, preview, raised panels, inputs |
| `surface-hover` | `#f3f1ec` | Hover backgrounds |
| `ink` | `#1c1917` | Primary body text |
| `ink-muted` | `#78716c` | Secondary text, meta |
| `ink-subtle` | `#a8a29e` | Placeholders, subtle meta |
| `line` | `#e7e5e4` | Hairline borders, dividers |
| `line-strong` | `#d6d3d1` | Input borders |

| Token | Value | Use |
|---|---|---|
| `teal-50` | `#f0f9f8` | Active row tints, soft accents |
| `teal-100` | `#d5edea` | Focus ring, highlights |
| `teal-500` | `#14b8a6` | Status dots, focus border |
| `teal-600` | `#0f766e` | Primary actions, active text |
| `teal-700` | `#115e59` | Primary hover |

Functional: `amber-*` (warnings, dirty, behind), `rose-*` (errors, destructive). Monaco defaults (`zinc-*` border, body text) are left as-is.

No dark classes. Tailwind v4 CSS-first only.

## Typography

- **UI:** `font-sans` → Inter Variable (via `@fontsource-variable/inter`).
- **Mono:** `font-mono` → JetBrains Mono Variable (via `@fontsource-variable/jetbrains-mono`).
- **Monaco editor** also uses JetBrains Mono for consistency.
- Brand wordmark: `font-semibold tracking-tight`.
- Section headers: `text-[11px] uppercase tracking-wider text-ink-subtle`.
- File paths: `font-mono text-ink-muted`.
- Meta: `text-xs text-ink-subtle`.

## Icons

lucide-react, tree-shakeable. Wrapped via `Icon` component with `size-4 stroke-[1.5] text-current`. Curated set: `Leaf`, `Plus`, `FolderPlus`, `Pencil`, `Trash2`, `ChevronDown`, `ChevronRight`, `X`, `Settings`, `RotateCw`, `GitBranch`, `ArrowUp`, `ArrowDown`, `Files`, `GitGraph`.

## Layout Skeleton

```
┌──────────────────────────────────────────────────────────────────────┐
│ TopBar: # typst-leaf · project · main.typ  Save  LSP  PRV  @    │
├──────────┬───────────────────────────────────────────────────────────┤
│ Sidebar  │                                                           │
│  Files   │                                                           │
│  ─────── │                     Monaco Editor                          │
│  ▣ main  │                    (typst-leaf-light theme)               │
│  ▣ lib/  │                                                           │
│  Git     │                                                           │
│  Settings├─────────────────────────────────────┬─────────────────────┤
│          │           Editor (resizable)        │      Preview       │
│          │                                     │     (iframe)       │
│          │                                     │                    │
└──────────┴─────────────────────────────────────┴─────────────────────┘
│ StatusBar: main · clean · LSP · Preview · vim · saving…                   │
└──────────────────────────────────────────────────────────────────────┘
```

## Component Specs

### TopBar
- `h-12`, `bg-canvas`, `border-b border-line`.
- Left: `Leaf` icon (teal-600, size-5), "typst-leaf" (semibold, tracking-tight), middot divider, project name, `/` divider, file path (`font-mono text-ink-subtle`).
- Right: LSP/Preview Chip (hidden when no file), `Button primary` Save, `IconButton` Settings.
- When no project: text-centered "Select a project to begin".

### Sidebar
- `w-72`, `bg-canvas`, `border-r border-line`.
- ProjectPicker at top with `border-b border-line`.
- Three icon+label tabs (Files, Git, Settings): active = teal text + 2px teal bottom border on surface; inactive = ink-muted.
- Section headers: `uppercase tracking-wider text-ink-subtle text-[11px]`.

### StatusBar
- `h-7`, `bg-canvas`, `border-t border-line`.
- `GitBranch` icon + branch name, clean/dirty, ahead/behind with arrows.
- LSP/Preview Chip.
- Vim indicator and saving indicator.

### ResizableSplit
- `flex h-full min-h-0 w-full flex-1`.
- Divider: `w-1 bg-line hover:bg-teal-400`, `cursor-col-resize`, `transition-colors`.
- Panels: `min-w-[280px] overflow-hidden`.

### EmptyState
- Centered with muted `Leaf` icon, message, and optional hint.
- `text-ink-subtle`.

### ToastHost
- Fixed bottom-right, `rounded-lg shadow-sm`.
- `StatusDot` + message + lucide `X` close.
- Kinds: teal (success), rose (error), neutral (info).

### Preview
- `bg-surface`, toolbar with "Preview" label, status Chip, `RotateCw` reload button.
- Content: full-height iframe or centered placeholder text.

### Editor
- `h-full flex flex-col min-h-0`. Toolbar: mono file path, Vim toggle, vim status.
- Monaco with custom `typst-leaf-light` theme (warm near-white background, restrained rainbow-free syntax palette).

### FileTree
- Nested tree with `hover:bg-surface-hover` rows, active file `bg-teal-50 text-teal-700`.
- Inline rename/create inputs with `border-teal-400`.
- Hover actions with lucide icons (Plus, FolderPlus, Pencil, Trash2).
- Dirty files marked with amber dot.

### GitPanel
- Section header with branch name, ahead/behind arrows.
- Changed files with lucide status icons (Plus/Pencil/X/HelpCircle).
- Button primary Commit, Button secondary Push/Pull with ArrowUp/ArrowDown icons.
- Collapsible Log with chevron.

### SettingsPanel
- "Git Identity" section.
- TextInputs for name/email, Button primary Save, Button secondary Clear.

## States

- **No project:** large empty state in main area; sidebar shows project list.
- **Connecting:** amber pulse dot on LSP/Preview chips.
- **Error:** rose-600 text in error banner and toasts.
- **Save error:** rose toast + dirty marker on file name.
- **Git dirty:** amber dot on file in tree.

## Motion

- Hover/focus: `transition-colors duration-150`.
- Button press: `active:scale-[0.98]` on primary buttons.
- Toast: none (instant show/hide).
- Connecting dots: `animate-pulse`.

## Accessibility

- Visible focus rings: `focus-visible:ring-2 focus-visible:ring-teal-100 focus-visible:ring-offset-2`.
- All interactive controls keyboard-reachable.
- State communicated by text + color, never color alone.

## Don'ts

- No gradients on chrome.
- No shadows on panels (only on toasts).
- No animated chrome unless real state change.
- No emoji in product UI — icons only from lucide.
- No dark mode.