typst-leaf/DESIGN.md

DESIGN.md — typst-leaf UI Rehaul

This document is the aesthetic reference for the next chunk in PLAN.md. Every UI decision in PLAN.md should match this guide. Direction is "document editor" — warmth, restraint, a thin layer of leaf.

Brand

• Name: typst-leaf — warm, organic, paper-and-ink.
• Personality: quiet, considered, a serious editor for prose, papers, and beautiful documents.
• Not "developer marketing." Not "dashboard SaaS." Closer to a focused notebook.

Aesthetic Pillars

1. Paper, not glass. Surfaces are warm off-white, not slate. Borders separate panels; we don't blur or float.
2. Functional color, decorative restraint. Greens only when communicating success/active/leaf. Use amber for warnings, slate for muted text, rose for errors. No gradients on chrome.
3. Typography is the interface. System sans for chrome, monospace for paths/git/lsp status. We say things in words, not icons.
4. A whisper, not a shout. Rounded corners are subtle (rounded-md). Focus rings are visible but quiet.

Palette (Tailwind v4 via CSS-first)

Token	Use	Tailwind class
Page background	Shell chrome	bg-stone-50
Panel surface	Cards, panels	bg-white
Sidebar	Activity + sections	bg-stone-50 with inner panels bg-white
Text primary	Body	text-zinc-800
Text muted	Meta	text-zinc-500
Text subtle	File paths	text-zinc-400
Divider	1px borders	border-zinc-200
Hover surface	Buttons/list rows	hover:bg-stone-100
Accent (primary)	Save, commit	bg-emerald-600 hover:bg-emerald-700 text-white
Accent (soft)	Active file, focus	bg-emerald-50 text-emerald-800 ring-emerald-200
Warning	Behind	text-amber-600
Error	Dirty error	text-rose-600
Pill bg (status)	Status chips	bg-white border-zinc-200

We do not introduce dark classes. Tailwind v4 is in CSS-first mode (@import "tailwindcss"); tokens live in plain CSS, not tailwind.config.js.

Typography

• UI: font-sans (system stack already from Tailwind).
• Monospace: font-mono for paths, git refs, LSP logs, status messages.
• Toolbar/header: text-sm font-medium tracking-tight.
• Meta and toasts: text-xs text-zinc-500.
• File names: text-sm font-mono.

Layout Skeleton

┌──────────────────────────────────────────────────────────────────────┐
│ TopBar:  leaf  ·  [project ▾]  ·  main.typ  ·  Save  ·  ●LSP  ◌PRV  │
├──────────┬───────────────────────────────────────────────────────────┤
│ Sidebar  │                                                           │
│  Files   │                                                           │
│  ▣ main  │                        Monaco Editor                       │
│  ▣ lib/  │                                                           │
│  Git     │                                                           │
│  ⚙ set   │                                                           │
│          ├─────────────────────────────────────┬─────────────────────┤
│          │           Editor (resizable)        │      Preview       │
│          │                                     │     (iframe)       │
│          │                                     │                    │
└──────────┴─────────────────────────────────────┴─────────────────────┘
│ StatusBar: main · clean · ready · vim:n · 1:23                              │
└──────────────────────────────────────────────────────────────────────┘

Component Specs (Tailwind)

TopBar

<header class="flex items-center gap-3 border-b border-zinc-200 bg-white px-4 h-11">
  <span class="font-semibold tracking-tight">typst-leaf</span>
  <span class="text-zinc-300">·</span>
  <button class="text-sm hover:bg-stone-100 px-2 py-1 rounded-md">project ▾</button>
  <span class="ml-2 text-sm font-mono text-zinc-500 truncate">main.typ</span>
  <span class="ml-auto flex items-center gap-2">
    <span class="text-xs px-2 py-0.5 rounded-full bg-emerald-50 text-emerald-700 border border-emerald-200">LSP · ready</span>
    <span class="text-xs px-2 py-0.5 rounded-full bg-stone-100 text-zinc-600 border border-zinc-200">PRV · starting</span>
    <button class="text-sm bg-emerald-600 hover:bg-emerald-700 text-white rounded-md px-3 py-1">Save</button>
    <button class="text-sm text-zinc-500 hover:bg-stone-100 px-2 py-1 rounded-md">⚙</button>
  </span>
</header>

Sidebar (PanelSection + tabs)

<aside class="w-64 border-r border-zinc-200 bg-stone-50 flex flex-col min-h-0">
  <div class="px-3 py-2 text-[11px] uppercase tracking-wider text-zinc-400">Files</div>
  <nav class="flex-1 overflow-auto p-1">
    <button class="w-full text-left text-sm px-2 py-1 rounded-md bg-emerald-50 text-emerald-800">main.typ</button>
    <button class="w-full text-left text-sm px-2 py-1 rounded-md hover:bg-stone-100">lib/util.typ</button>
  </nav>
  <div class="border-t border-zinc-200 p-2 text-xs text-zinc-500">12 uncommitted</div>
</aside>

ResizableSplit

<div class="flex h-full min-h-0">
  <div class="min-w-[280px]" style={{ width: `${left}%` }}>/* editor */</div>
  <div
    role="separator"
    aria-orientation="vertical"
    class="w-1 bg-zinc-200 hover:bg-emerald-300 cursor-col-resize"
    onPointerDown={startDrag}
    onDoubleClick={reset}
  />
  <div class="flex-1 min-w-[280px]">/* preview */</div>
</div>

EmptyState

<div class="flex-1 flex flex-col items-center justify-center text-zinc-400 gap-2">
  <div class="text-sm">Open a file from the sidebar.</div>
  <div class="text-xs text-zinc-500">Tip: ⌘P to jump, ⌘S to save.</div>
</div>

Toast

<div class="fixed bottom-4 right-4 z-50 flex flex-col gap-2">
  <div class="bg-white border border-zinc-200 rounded-md shadow-sm px-3 py-2 text-sm">
    <span class="text-emerald-700 mr-2">●</span>
    Committed <span class="font-mono">a1b2c3d</span>
  </div>
</div>

Status chips

<span class="text-[11px] px-2 py-0.5 rounded-full border">
  <span class="inline-block size-1.5 rounded-full bg-emerald-500 mr-1" />
  LSP · ready
</span>

States

• No project: large empty state in main area; sidebar shows "No project yet."
• Connecting: preview shows "starting…" with a quiet spinner (CSS, not library).
• External preview source: toast "Source outside project — ignored."
• Save error: rose-600 message in toast + small dot in TopBar file path.
• Git dirty: emerald-50 row tint + small dot next to filename in tree.

Motion

• Hover: transition-colors duration-100.
• Splitter drag: no transition.
• Toast in/out: 150ms opacity, no spring.

Accessibility

• Visible focus rings: focus-visible:ring-2 focus-visible:ring-emerald-300 focus-visible:ring-offset-1.
• All interactive controls reachable by keyboard.
• Status communicated by text + color, never color alone.

Don'ts

• No gradients on chrome.
• No shadows on whitespace panels.
• No animated chrome unless it's a real state change.
• No emoji decorations in product UI (only as icons in narrow toolbars).

Thumbnail: vibe check

Imagine a warm, slightly off-white IDE with a single green accent for "commit ready" and a quiet three-dot status footer. It's the IDE equivalent of a blank page of cream paper, not a glass dashboard.