summary
Mockup Summary: Markdown Documentation Editor (MDE)
Feature: MDE - Markdown Documentation Editor Created: 2025-11-27 Designer: Bruce (UI Designer)
Overview
This document summarizes the ASCII mockup variations created for the MDE feature and provides recommendations for implementation.
Mockup Files
| File | Variations | Status |
|---|---|---|
| editor-variations.md | 5 layouts | Complete |
| create-form-variations.md | 5 form patterns | Complete |
| delete-confirmation.md | 5 modal designs | Complete |
| concurrent-edit-indicator.md | 5 indicator styles | Complete |
| search-filter.md | 5 search patterns | Complete |
| auto-save-indicator.md | 5 status displays | Complete |
Recommended Design Decisions
1. Editor Layout
Recommendation: Option A - Equal 50/50 Split
┌─────────────────────────────────────────────────────────────────┐│ [Doc Title] [Cancel] [Save] │├─────────────────────────────┬───────────────────────────────────┤│ EDITOR (50%) │ PREVIEW (50%) ││ │ ││ # Heading │ Heading ││ Content... │ Content... │├─────────────────────────────┴───────────────────────────────────┤│ [Auto-saved: 30s ago] [▼ Metadata] │└─────────────────────────────────────────────────────────────────┘Rationale:
- Matches common patterns (GitHub, Notion)
- Equal importance to editing and previewing
- Works well at typical desktop widths (1200px+)
- Can add resizing (Option C) as enhancement later
2. Create New Document Form
Recommendation: Option A - Simple Single-Step Form
┌──────────────────────────────────────────────────────────────────┐│ Create New Agent │├──────────────────────────────────────────────────────────────────┤│ Name * ││ ┌────────────────────────────────────────────────────────────┐ ││ │ discovery-agent │ ││ └────────────────────────────────────────────────────────────┘ ││ Filename: discovery-agent.md ││ ││ Description * ││ ┌────────────────────────────────────────────────────────────┐ ││ │ Explores codebases to find patterns... │ ││ └────────────────────────────────────────────────────────────┘ ││ ││ Tools (optional) Model (optional) ││ [Select...] [Select...] │├──────────────────────────────────────────────────────────────────┤│ [Cancel] [Create Agent →] │└──────────────────────────────────────────────────────────────────┘Rationale:
- Fastest to implement
- Familiar pattern
- All fields visible at once
- Can evolve to accordion (Option D) for complex types
3. Delete Confirmation
Recommendation: Option C - Warning with Details
┌────────────────────────────────────────────────────────┐│ ⚠️ Delete "discovery-agent"? │├────────────────────────────────────────────────────────┤│ ┌─ Document Details ─────────────────────────────┐ ││ │ Type: Agent │ ││ │ Path: .claude/agents/discovery-agent.md │ ││ │ Last edited: Nov 27, 2025 by Will │ ││ └────────────────────────────────────────────────┘ ││ ││ ❗ This action cannot be undone. │├────────────────────────────────────────────────────────┤│ [Cancel] [Delete Document] │└────────────────────────────────────────────────────────┘Rationale:
- Shows context to verify correct file
- Standard confirmation without excessive friction
- Add file list for folder deletion (from Option D)
4. Concurrent Edit Indicator
Recommendation: Combination Approach
View Mode: Status pill in header
│ Discovery Agent [🔒 Being edited by Will] [Edit] │Edit Confirmation: Dialog when clicking Edit
┌─────────────────────────────────────────────────────────┐│ Someone is already editing ││ Will started editing 5 minutes ago. ││ [Wait & Refresh] [Edit Anyway] │└─────────────────────────────────────────────────────────┘Rationale:
- Matches “soft lock” decision from spec
- Clear but not blocking
- Warns at the right moment
5. Search & Filter
Recommendation: Header Search + Index Filters
Global header search:
│ TC Portal [🔍 Search documentation... ] 👤 │Index page filters:
│ ┌──────────────────────────────┐ Sort: [▼ Name] ││ │ 🔍 Filter agents... │ ││ └──────────────────────────────┘ │Rationale:
- Matches “client-side filtering” decision
- Two-level approach: global discovery + local filtering
- Add Cmd+K shortcut as future enhancement
6. Auto-Save Indicator
Recommendation: Option A - Footer Bar Status
├─────────────────────────────────────┴───────────────────────────┤│ Draft saved 30s ago [▼ Metadata] │└─────────────────────────────────────────────────────────────────┘States:
Draft saved 30s ago- normal (grey)Saving draft...- active (with spinner)Draft saved just now- success (brief green)⚠️ Unable to save draft- error (orange)
Rationale:
- Matches design spec decision (“subtle inline text”)
- Always visible without cluttering main UI
- Clear state transitions
Component Hierarchy
DocumentEditor/├── EditorHeader│ ├── DocumentTitle│ ├── ConcurrentEditBadge (optional)│ ├── CancelButton│ └── SaveButton├── EditorPane (split view)│ ├── MarkdownEditor│ └── MarkdownPreview├── EditorFooter│ ├── AutoSaveStatus│ └── MetadataToggle└── MetadataPanel (collapsible) ├── NameField ├── DescriptionField ├── ToolsSelector ├── ModelSelector └── RelatedItemsSelector
CreateDocumentModal/├── ModalHeader├── CreateForm│ ├── NameField│ ├── DescriptionField│ ├── OptionalFields│ └── FilenamePreview└── ModalFooter ├── CancelButton └── CreateButton
DeleteConfirmationModal/├── WarningIcon├── DocumentDetails├── NestedContentList (if applicable)└── ConfirmationButtons
SearchInterface/├── GlobalSearchBar (header)└── IndexPageFilter (per-type pages)Responsive Breakpoints
| Breakpoint | Layout Adaptation |
|---|---|
| Desktop (1024px+) | Full split-pane editor, all features |
| Tablet (768-1023px) | Stacked editor/preview with tabs, simplified metadata |
| Mobile (320-767px) | View-only mode, “Edit on desktop” message |
Next Steps
- Review recommendations with stakeholders
- Finalize editor library choice (check existing codebase)
- Create high-fidelity mockups if needed (Figma/HTML)
- Proceed to technical planning with
/speckit.plan
Design Spec Reference
All mockups align with decisions documented in design-spec.md:
- Split-pane layout (same page toggle)
- Collapsible metadata panel below editor
- View-only on mobile
- Subtle inline auto-save text
- Soft lock for concurrent editing