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

// 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

// 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