simplenote-web/ui/SPEC.md

# SimpleNote Web - UI/UX Specification

## 1. Overview

### 1.1 Purpose
SimpleNote Web is the frontend interface for the SimpleNote document management system. It provides a clean, efficient way to browse, create, edit, and manage documents organized in nested libraries with tag-based filtering.

### 1.2 Target Users
- Technical users and agents creating/managing documentation
- Teams using CLI tools to push documents that need visual review
- Anyone preferring a Joplin-like experience with a modern dark-mode interface

### 1.3 Tech Stack
- **Framework**: Vanilla JS with modern ES modules (no framework dependency for simplicity)
- **Styling**: CSS custom properties for theming (dark/light modes)
- **Markdown**: `marked` library for rendering
- **Icons**: Lucide Icons (SVG-based, MIT licensed)
- **HTTP Client**: Native Fetch API
- **State**: Simple pub/sub pattern with localStorage for preferences

---

## 2. Design Principles

### 2.1 Core Principles
1. **Content-First**: Documents are the hero; UI stays out of the way
2. **Keyboard-Friendly**: Common actions accessible via shortcuts
3. **Information Density**: Compact but readable; optimized for power users
4. **Progressive Disclosure**: Show details on demand, not all at once
5. **Dark Mode Primary**: Inspired by Mission Control dashboard aesthetics

### 2.2 Layout Architecture
```
┌─────────────────────────────────────────────────────────────┐
│  Header (Logo + Search + User Actions)                      │
├──────────────┬──────────────────────────────────────────────┤
│              │                                              │
│   Sidebar    │              Main Content Area               │
│   (Library   │                                              │
│    Tree +    │   - Document List (Dashboard)               │
│    Tags)     │   - Document Viewer                          │
│              │   - Document Editor                          │
│              │   - Library Browser                          │
│              │                                              │
├──────────────┴──────────────────────────────────────────────┤
│  Status Bar (optional: sync status, doc count)              │
└─────────────────────────────────────────────────────────────┘
```

### 2.3 Responsive Strategy
- **Desktop (>1024px)**: Full sidebar + content layout
- **Tablet (768-1024px)**: Collapsible sidebar, full content
- **Mobile (<768px)**: Bottom navigation, stacked layout, slide-over panels

---

## 3. Views Specification

### 3.1 Dashboard / Main View

**Purpose**: Central hub showing documents with filtering and navigation.

**Components**:
- **Header Bar**: Logo, global search input, theme toggle, settings
- **Sidebar (left)**:
  - Library tree (collapsible, nested)
  - Quick filters: All Documents, Recent, Favorites
  - Tag cloud/list with counts
- **Main Content**:
  - Toolbar: View toggle (list/grid), sort options, bulk actions
  - Document cards/list with title, tags, type badge, date, status
  - Quick actions: New Document, New Library buttons

**URL**: `/` or `/documents`

**Keyboard Shortcuts**:
- `Ctrl/Cmd + K`: Focus search
- `Ctrl/Cmd + N`: New document
- `Ctrl/Cmd + Shift + N`: New library
- `Escape`: Clear filters/search

### 3.2 Document Viewer

**Purpose**: Read-only view of a document with rendered markdown.

**Components**:
- **Header**: Back button, document title, action buttons (Edit, Export, Delete)
- **Metadata Panel** (collapsible sidebar or dropdown):
  - Type badge (requirement/note/spec/general)
  - Status badge (draft/approved/implemented)
  - Priority indicator (high/medium/low with color)
  - Tags as clickable pills
  - Author
  - Created/Updated timestamps
- **Content Area**: Rendered markdown with:
  - Syntax highlighting for code blocks
  - Styled tables
  - Checkbox rendering for criteria lists
  - Anchor links for headings

**URL**: `/documents/:id`

**Keyboard Shortcuts**:
- `E`: Edit document
- `X`: Export markdown
- `Delete/Backspace`: Delete (with confirmation)
- `Escape`: Back to list

### 3.3 Document Editor

**Purpose**: Create or edit documents with live preview.

**Components**:
- **Header**: Cancel/Save buttons, document title (editable)
- **Editor Toolbar**:
  - Markdown formatting buttons (bold, italic, headers, lists, code, link)
  - Insert template dropdown
  - Preview toggle (split view or tabbed)
- **Frontmatter Panel**:
  - Title input
  - Type selector (dropdown)
  - Status selector (dropdown)
  - Priority selector (dropdown)
  - Tags input (chip-style, autocomplete)
  - Library selector (dropdown with tree view)
- **Editor Area**:
  - Monaco-style textarea with markdown syntax highlighting
  - OR CodeMirror/MarkText integration (future)
- **Preview Pane**: Live rendered markdown (toggleable)
- **Auto-save Indicator**: "Saved" / "Saving..." / "Unsaved changes"

**URL**: `/documents/:id/edit` or `/documents/new`

**Keyboard Shortcuts**:
- `Ctrl/Cmd + S`: Save
- `Ctrl/Cmd + B`: Bold
- `Ctrl/Cmd + I`: Italic
- `Ctrl/Cmd + K`: Insert link
- `Ctrl/Cmd + Shift + P`: Toggle preview
- `Escape`: Discard changes (with confirmation)

### 3.4 Library Browser

**Purpose**: Navigate and manage library hierarchy.

**Components**:
- **Breadcrumbs**: Path from root to current library
- **Library Tree** (sidebar): Expandable/collapsible nested view
- **Main Content**:
  - Header: Current library name, document count
  - Actions: New Document, New Sub-library, Rename, Delete
  - Content list: Documents and sub-libraries mixed
  - Drag-and-drop reordering (future)

**URL**: `/libraries/:id`

**Actions**:
- Click library → navigate to library view
- Click document → open viewer
- Right-click/long-press → context menu (Rename, Delete, Move)
- "+" buttons for creating new items

**Keyboard Shortcuts**:
- `Ctrl/Cmd + Shift + N`: New sub-library
- `R`: Rename selected
- `Delete`: Delete (with confirmation)
- `Escape`: Go to parent library

---

## 4. Interaction Patterns

### 4.1 Navigation
- Sidebar persists across views (single-page app behavior)
- Breadcrumbs for deep library navigation
- Browser back/forward support via History API

### 4.2 Search
- Real-time filtering as user types (debounced 300ms)
- Search scope: title, content, tags
- Highlight matching terms in results
- Empty state: "No documents found"

### 4.3 Tag Filtering
- Click tag in sidebar → filter documents
- Click tag pill in document → filter by that tag
- Multiple tags = AND filter
- Active filters shown as removable chips

### 4.4 Confirmation Dialogs
- Delete operations: Modal with confirmation
- Unsaved changes: Modal asking to save/discard
- All modals: Escape to cancel, Enter to confirm (when safe)

### 4.5 Notifications/Toasts
- Success: Green, auto-dismiss 3s
- Error: Red, persistent until dismissed
- Info: Blue, auto-dismiss 5s
- Position: Bottom-right

---

## 5. Data Flow

### 5.1 API Integration
All UI data comes from the REST API at `/api/v1`.

**Auth Flow**:
1. User enters token in settings or login page
2. Token stored in localStorage
3. All API requests include `Authorization: Bearer <token>` header
4. 401 response → clear token, show login

**Endpoints Used by UI**:
```
GET    /api/v1/documents         → Dashboard document list
GET    /api/v1/documents/:id     → Document viewer
POST   /api/v1/documents         → Create document
PUT    /api/v1/documents/:id     → Update document
DELETE /api/v1/documents/:id     → Delete document
GET    /api/v1/documents/:id/export → Export markdown
GET    /api/v1/libraries         → Library tree (root)
GET    /api/v1/libraries/:id     → Library contents
GET    /api/v1/libraries/:id/tree → Full library tree
POST   /api/v1/libraries         → Create library
DELETE /api/v1/libraries/:id     → Delete library
GET    /api/v1/tags              → Tag list with counts
GET    /api/v1/tags/:tag/documents → Filtered documents
```

### 5.2 State Management
```javascript
// App state (simple pub/sub)
const state = {
  documents: [],
  libraries: [],
  tags: [],
  currentView: 'dashboard', // dashboard|viewer|editor|library
  currentDocument: null,
  currentLibrary: null,
  filters: { tag: null, library: null, search: '' },
  preferences: { theme: 'dark' }
};
```

### 5.3 Auto-save Implementation
```javascript
// Debounced auto-save during editing
let saveTimeout;
function onEditorChange(content) {
  clearTimeout(saveTimeout);
  ui.setSaving();
  saveTimeout = setTimeout(() => {
    api.updateDocument(id, { content }).then(() => {
      ui.setSaved();
    }).catch(() => {
      ui.setError('Auto-save failed');
    });
  }, 2000); // 2 second debounce
}
```

---

## 6. Accessibility

### 6.1 Requirements
- All interactive elements keyboard accessible
- Focus visible indicators (custom styled)
- ARIA labels on icons and non-text elements
- Color contrast ratio ≥ 4.5:1 (WCAG AA)
- Screen reader announcements for dynamic content

### 6.2 Keyboard Navigation
- Tab order follows visual layout
- Focus trapped in modals
- Skip-to-content link
- Arrow keys for tree/list navigation

---

## 7. Error Handling

### 7.1 Network Errors
- Show toast notification
- Retry button for failed requests
- Offline indicator in status bar

### 7.2 Validation Errors
- Inline field errors in forms
- Red border on invalid fields
- Error message below field

### 7.3 Empty States
- No documents: Illustration + "Create your first document" CTA
- No search results: "No matches found" + clear filters button
- No libraries: "Create a library to organize your documents"

---

## 8. Future Enhancements (Out of Scope for v1)

- Drag-and-drop document organization
- Document versioning/history
- Collaborative editing
- Full-text search
- Document templates gallery
- Export to PDF/HTML
- Mobile native app