Skip to content
Trilogy Care Logo TC Docs

design spec

Design Specification: Markdown Documentation Editor

Feature: MDE - Markdown Documentation Editor Initiative: TP-2141-Work-Management Created: 2025-11-27 Designer: Bruce (UI Designer) Status: Draft Complete

Overview

What We’re Building

A comprehensive markdown documentation editor that expands the existing read-only documentation viewer into a full content management system. Users will be able to create, edit, update, and delete markdown documentation files (agents, commands, skills, MCP servers, initiatives, epics) directly through the web interface.

Design Philosophy

[TO BE DETERMINED BASED ON STAKEHOLDER INPUT]

This is an internal staff tool focused on productivity and efficiency. The interface should prioritize:

  • Information density appropriate for power users
  • Quick access to editing functions
  • Clear feedback on document state (saved, editing, conflicts)
  • Minimal friction for common workflows (edit → save, create → populate metadata → save)

User Context

Target Users

  • Primary: Team members and business users who need to maintain documentation (Product Managers, Developers, Operations staff)
  • Secondary: Any authenticated user with documentation access (open access model with audit logging)

User Needs

  • Quick editing of existing documentation without leaving the browser
  • Structured creation of new documents with guided metadata entry
  • Clear indication of document state (who’s editing, unsaved changes, saved status)
  • Fast search and discovery of documentation
  • Confidence in data integrity (auto-save, validation, conflict handling)

Usage Patterns

  • Frequent: Editing existing docs to update content, Creating new command/skill documentation
  • Moderate: Creating new agents, Managing metadata, Searching documentation
  • Occasional: Deleting documents, Resolving edit conflicts, Creating initiatives/epics

Layout & Structure

Page Architecture

Decision: Same-page split-pane

User clicks “Edit” button → Same page transforms to show split-pane editor. No page navigation required. Preserves document context.

Editor Layout Pattern

Decision: Split-pane (side-by-side)

┌─────────────────────────────────────────────────────────────┐
│ [Doc Title]                    [Cancel] [Save]              │
├─────────────────────────────┬───────────────────────────────┤
│ EDITOR                      │ PREVIEW                       │
│                             │                               │
│ # Heading                   │ Heading                       │
│                             │ ─────────                     │
│ Content here...             │ Content here...               │
│                             │                               │
├─────────────────────────────┴───────────────────────────────┤
│ [Auto-saved: 30s ago]              [▼ Metadata]             │
├─────────────────────────────────────────────────────────────┤
│ ┌─ Metadata (collapsed by default, click to expand) ──────┐ │
│ │ Name: [____________]  Description: [________________]   │ │
│ │ Tools: [▼ Select]     Related: [▼ Select]              │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Rationale:

  • Live preview always visible (FR-003)
  • Minimal context switching
  • Matches common patterns (GitHub, Notion, etc.)
  • Fastest for edit-preview workflow

Information Architecture

Document View (Existing)

[Header: Doc Title]
[Metadata badges/chips]
[Rendered markdown content]
[Footer: Related documents, timestamps]

Edit Mode (New)

[TO BE DETERMINED BASED ON LAYOUT DECISIONS]

Create New Form (New)

[TO BE DETERMINED]

Component Inventory

Existing Components (Reuse)

  • Documentation viewer: Current page rendering markdown
  • Storybook components: 70+ available components at design.trilogycare.dev
  • Form components: Input, Textarea, Select, Checkbox, etc. from Reka UI
  • Feedback components: Toast notifications, Modal dialogs, Alert banners

New Components Required

1. Markdown Editor Component

[TO BE DETERMINED - QUESTION 3]

  • Use existing library (CodeMirror, Monaco, etc.) or custom implementation?
  • Must include: Syntax highlighting, Line numbers, Auto-indent, Keyboard shortcuts

2. Live Preview Component

  • Real-time markdown rendering
  • Scroll sync with editor (optional)
  • Same styling as main documentation viewer

3. Metadata Editor Form

  • Dynamic fields based on document type
  • Validation feedback inline
  • Related entity selectors (tools, related agents, etc.)

4. Document State Indicator

  • Auto-save status (“Saving…”, “Saved”, “Draft”)
  • Concurrent edit warning (“User X is editing”)
  • Unsaved changes warning

5. Create Document Form

  • Document type selector
  • Required metadata fields
  • Filename preview/generation
  • Directory location indicator

6. Delete Confirmation Modal

  • Clear warning message
  • Nested content warning for folders
  • Confirm/Cancel actions

7. Search & Filter Interface

  • Search input with live filtering
  • Document type filter chips
  • Result list with context snippets

Interaction Design

Primary User Flows

Flow 1: Edit Existing Document

1. User views document
2. Clicks "Edit" button → [TRANSITION TO EDIT MODE - TBD]
3. Sees editor loaded with current content
4. Makes changes (auto-save every 30s to localStorage)
5. Reviews live preview
6. Clicks "Save" → Server update → Success confirmation
   OR Clicks "Cancel" → Confirm discard changes → Return to view

Flow 2: Create New Document

1. User on index page (e.g., /agents)
2. Clicks "Create New Agent"
3. Sees form with metadata fields
4. Fills required fields (name, description)
5. Filename auto-generated, shown to user
6. Writes content in editor
7. Clicks "Save" → Validation → File created → Redirect to new document

Flow 3: Concurrent Edit Conflict

1. User A opens document for editing
2. User B sees "User A is editing this document" indicator
3. User B can choose to:
   - Wait and refresh
   - Proceed anyway (warned of conflict risk)
4. If both save: Last-write-wins, both changes logged

Keyboard Shortcuts

  • Cmd/Ctrl + S: Save document
  • Cmd/Ctrl + P: Toggle preview
  • Esc: Cancel edit (with confirmation if unsaved changes)
  • [Additional shortcuts TBD]

Component States

Markdown Editor States

  • Loading: Skeleton/spinner while fetching content
  • Editing: Active, accepts input
  • Auto-saving: Subtle indicator “Saving draft…”
  • Saved: Brief confirmation “Saved to server”
  • Error: Red banner with error message
  • Read-only: When conflict detected or permissions issue

Document Page States

  • View mode (current): Read-only rendered markdown
  • Edit mode: Active editor with preview
  • Creating: New document form + editor
  • Locked: “User X is editing” warning banner
  • Deleted: Removed, redirect to index

Validation States

  • Valid: Green checkmark, can save
  • Invalid: Red error messages, save disabled
  • Validating: Spinner while checking
  • Warning: Yellow caution (e.g., filename conflict suggestion)

Visual Design

Color Usage (Trilogy Care Brand)

Document State Indicators:

  • Editing/Active: Primary Blue (#4B7BBE)
  • Saved/Success: [Use existing success color from design system]
  • Warning/Conflict: Sun Yellow (#FEBD33) or Orange (#E0763C)
  • Error: Red (#E04B51)
  • Auto-saving: Sky Blue (#64BCEA)

Buttons & Actions:

  • Primary CTA (Save): Navy (#2C4C79) or Primary Blue (#4B7BBE)
  • Secondary (Cancel): Light Grey (#F2F2F2) with Text Primary
  • Destructive (Delete): Red (#E04B51)

Typography

  • Editor content: Monospace font (preserve existing editor defaults)
  • UI elements: Roboto Flex (body), Roboto Serif (headings if needed)
  • Metadata labels: Roboto Flex Semibold or Medium

Spacing

Follow 8px grid system:

  • Editor padding: 16px (1rem)
  • Button spacing: 8px gap between actions
  • Section spacing: 24px (1.5rem) between major sections
  • Form field spacing: 16px (1rem) between fields

Responsive Behavior

Desktop (Primary Target)

  • [LAYOUT TBD]: Split-pane, stacked, or tabbed editor
  • Full metadata sidebar/panel
  • All features accessible

Tablet (iPad)

  • [LAYOUT TBD]: May collapse to tabbed or stacked view
  • Metadata may become accordion or modal
  • Touch-friendly targets (44px minimum)

Mobile (320-767px) - View Only

Decision: No mobile editing

  • View-only mode for documentation
  • Show “Edit on desktop” message when Edit button tapped
  • Full viewing experience preserved
  • Keeps responsive design simple

Accessibility

WCAG Compliance

  • Focus indicators: Clear keyboard focus for all interactive elements
  • Color contrast: All text meets WCAG AA (4.5:1 for body, 3:1 for large)
  • Screen readers: Proper ARIA labels for editor state, validation messages
  • Keyboard navigation: Full functionality without mouse

Specific Considerations

  • Editor must support screen reader announcements for auto-save status
  • Validation errors announced to assistive tech
  • Confirmation modals must trap focus and return focus on close
  • Preview scrolling should not steal focus from editor

Edge Cases & Error Handling

Concurrent Editing

  • Soft lock: Show banner “User X is editing since [time]”
  • Override option: “Edit anyway” button with warning
  • Conflict resolution: Last-write-wins, log both changes with attribution

Session Expiry During Edit

  • Detection: Catch 401/403 API response
  • Action: Show re-login modal without losing editor content
  • Recovery: Draft preserved in localStorage, restored after successful auth

Auto-save Failures

  • Network error: Retry 3 times, then show persistent warning banner
  • Validation error: Show error but don’t block editing; fix issues before save
  • Quota exceeded: Warn user, disable auto-save, require manual save

Large Documents (>100KB)

  • Performance monitoring: Debounce preview updates if lag detected
  • Warning: Show notice if document exceeds recommended size
  • Optimization: Consider lazy-loading preview or pagination

Invalid Markdown

  • Linter: Optional inline warnings for broken syntax (non-blocking)
  • Preview: Render as best as possible, show errors in preview pane
  • Save: Allow saving invalid markdown (user responsibility)

Filename Conflicts

  • Detection: Check on create/rename before submission
  • Resolution: Suggest alternative filename with suffix (e.g., “command-name-2.md”)
  • User choice: Allow override if they understand consequences

Technical Considerations

Frontend Architecture

  • Vue 3 components using Composition API
  • Inertia.js for page navigation and form submissions
  • Tailwind CSS for styling
  • Reka UI for accessible primitives

Markdown Editor Library

Decision: CodeMirror 6

  • Modern, extensible architecture
  • Good Vue 3 support
  • Smaller bundle than Monaco
  • Syntax highlighting, line numbers built-in
  • Supports custom keybindings (Cmd+S for save)

State Management

  • Document content: Inertia page props for initial load
  • Draft state: localStorage with user/document key
  • Auto-save: Debounced API calls (30s interval or on pause)
  • Concurrent lock: Polling or WebSocket for “user is editing” status

Data Flow

1. Load: GET /documentation/{type}/{slug} → Inertia render
2. Edit: Fetch content if not in props → Load into editor
3. Auto-save: PUT /api/documentation/{id}/draft (localStorage backup)
4. Save: PUT /api/documentation/{id} → Validation → File write → Success
5. Create: POST /api/documentation → Validation → File create → Redirect

Open Questions

Resolved Decisions

  1. Layout & Editor Pattern → Split-pane on same page (editor left, preview right)
  2. Markdown Editor Library → CodeMirror 6
  3. Mobile Editing Support → View-only on mobile
  4. Metadata Editor Complexity → Collapsible panel below editor
  5. Search Interface Location → Client-side filtering on index pages (per spec clarification)

Remaining Questions (Low Priority - Can Defer to Implementation)

  • Exact toolbar buttons for editor (bold, italic, link, code block shortcuts)
  • Dark theme support for editor (follow system preference or toggle?)
  • Scroll sync between editor and preview (nice-to-have)

Next Steps

  1. Answer design clarification questions (stakeholder input needed)
  2. Review existing Storybook components for reusable patterns
  3. Create low-fidelity wireframes for key layouts
  4. Prototype editor interaction in Canvas tool
  5. Validate responsive behavior across viewport sizes
  6. Document component specifications for developer handoff

Clarifications Log

Session 2025-11-27

  • Q: Editor layout pattern (same-page toggle vs dedicated page vs modal vs split-pane)? → A: Option B - Split-pane on same page (Editor left, Preview right, no navigation)
  • Q: Markdown editor library? → A: CodeMirror 6 - Modern, extensible, good Vue support, smaller bundle than Monaco
  • Q: Mobile editing support? → A: Option B - View-only on mobile (editing is desktop-only, simpler responsive design)
  • Q: Metadata editor location? → A: Option B - Collapsible panel below editor (clean editor area, expand when needed)
  • Q: Auto-save status indicator? → A: Option A - Subtle inline text (“Saved 30s ago” / “Saving…” in footer bar)

Appendix

  • Feature Spec: spec.md (same directory)
  • Storybook: https://design.trilogycare.dev
  • Trilogy Care Brand Guidelines: (see UI Designer agent system prompt)

Design Artifacts

[TO BE ADDED]

  • Wireframes
  • Component mockups
  • Interaction prototypes
  • Responsive layouts
  • Final design handoff files