# Product Design

## Design Principles

* Put the editor first.
* Keep project structure visible without letting it dominate the workspace.
* Favor explicit saves and clear dirty state.
* Keep filesystem effects predictable.
* Avoid project-local metadata in this version.

## Workspace

The editing workspace fills the full browser window. A persistent 48 px header holds all navigation; the editor occupies the remaining space. A left navbar slides in to show the file tree; a right aside column slides in when a panel is pinned.

```text
+-----------------------------------------------------------------------+
| ☰ W Wikied v0.8.7 | filename pill (Ctrl+P) [dot] | [Preview/Rich] [Styles] | [Save] [Git] | outline  recent  settings  about |
+-----------------------------------------------------------------------+
| [Navbar: file tree]  | Editor canvas (Rich or Preview) | [Aside: pinned panel]  |
| (accent-tinted bg)   |   [floating preview pill]       |                        |
|                      |                                 |                        |
+-----------------------------------------------------------------------+
| Status bar (accent bg): path · Saved/Unsaved · mode · Markdown · UTF-8 · LF |
+-----------------------------------------------------------------------+
```

The orange dot beside the filename pill indicates the active file has unsaved changes. The Save button and Git button appear in the right action group after a vertical divider. The left navbar and status bar are tinted with the active accent color.

![Wikied editor workspace](images/workspace-source.png)

## Top Bar

### Brand

The Wikied "W" mark, wordmark, and version badge appear at the left of the header.

### Filename Pill

The center of the header shows a pill button with the basename of the active file, or "Open a file…" when nothing is open. An orange dot appears to the right of the pill when the active file has unsaved changes.

Clicking the pill or pressing `Ctrl+P` expands it to an inline file search combobox:

* The combobox lists all files in the workspace root recursively.
* Typing filters options by path segment (case-insensitive).
* Markdown files are selectable; non-Markdown files are shown dimmed.
* Selecting a file opens it and collapses the picker.
* `Escape` collapses without selection.

### Action Icons

Icon buttons appear at the right of the header, separated from the mode controls by a vertical divider:

| Icon     | Action                                                                         |
| -------- | ------------------------------------------------------------------------------ |
| Save     | Opens a popover with Save (current file) and Save all; badge shows dirty count |
| Git      | Opens a popover with Commit, Push, and Pull; badge shows changed-file count    |
| Outline  | Opens the Outline drawer or unpins it from the aside                           |
| Recent   | Opens the Recent files drawer or unpins it from the aside                      |
| Settings | Opens a popover with theme and autosave controls                               |
| About    | Opens a modal with app information                                             |

The Git button is only shown when the workspace root is a git repository. Its badge updates on every file save and every 10 seconds.

## Save Button

The Save button (floppy-disk icon) shows an orange indicator badge with the count of files that have unsaved changes.

* **Save** — saves the currently active file (equivalent to `Ctrl+S`).
* **Save all** — saves every dirty file. Unsaved edits survive file switches: when leaving a dirty file its content and revision are cached in memory; switching back restores the cached edits.

Both actions are disabled when no files are dirty.

## Git Button

The Git button (branch icon) is visible when the workspace root is a git repository.

* **Commit…** — opens a modal with a commit message input. On confirm, runs `git add -A` then `git commit`. Shows the error inline if the commit fails.
* **Push** — runs `git push` and shows the result in the popover.
* **Pull** — runs `git pull` and shows the result in the popover.

Authentication relies on the system's existing git credentials (SSH keys, OS credential manager). No auth UI is provided.

## Clone on Empty Root

When wikied starts in a directory with no files, the browser shows a modal before loading the workspace:

* **Clone Repository** — accepts a git URL, calls the server clone endpoint, and loads the cloned content as the workspace.
* **Start Empty** — dismisses the modal; the workspace loads as a blank directory.

The `--git <url>` CLI flag is an alternative: it clones before starting the server, so no browser interaction is needed.

## Right Panel System

### Floating Drawer

Clicking Outline or Recent opens a right-side Drawer (300 px, with overlay). Each drawer header includes a **Pin to sidebar** button.

### Pinned Aside

Pinning a panel closes the drawer and opens `AppShell.Aside` with the same panel content. Only one panel can be pinned at a time. An unpin button appears in the aside header. The aside is 300 px wide (fixed in this version).

## Editor Canvas

### Floating Preview Pill

An absolutely positioned pill button appears at the top-right of the editor content area.

* **Rich mode**: shows a "Preview" label. Click switches to Preview.
* **Preview mode**: shows a "Rich" label. Click switches back. A chevron ActionIcon opens a popover with a style selector.

### Rich Mode

Rich mode is the default writing surface. It uses MDXEditor and includes controls for common authoring tasks: headings, emphasis, lists, links, images, tables, thematic breaks, code blocks, frontmatter, and admonitions.

### Preview Mode

Preview mode renders GitHub-flavored Markdown. Mermaid fenced code blocks render as diagrams.

![Wikied preview with Mermaid support](images/preview-mermaid.png)

Relative document links in Preview mode are intercepted by the app. The target path resolves from the active document directory, opens in the same editor, and asks whether to save first when the current file is dirty.

The Preview style selector (accessible from the floating pill chevron) includes: Default, GitHub, Docs, Print, and Minimal presets.

## Dirty State And Saving

The current dirty state appears in:

* An orange dot to the right of the filename pill.
* An orange count badge on the Save button in the header.
* The "Unsaved" badge in the status bar (green "Saved" when clean).
* Orange filename text and a Save icon on the active file row in the file tree.

![Wikied dirty document state](images/dirty-document.png)

Manual save is available through:

* `Ctrl+S` on Windows/Linux.
* `Cmd+S` on macOS.
* The Save button popover in the header.

Autosave runs after a short delay when enabled in the Settings popover.

## File Tree

The left navbar (260 px, collapsible) shows the workspace file tree. The navbar background is tinted with the active accent color (shade 0), and the divider between the navbar header and the tree body uses accent shade 2.

* Markdown files are selectable (full opacity); non-Markdown files shown dimmed.
* Directories expand and collapse; expand state is preserved during the session.
* The active file row is highlighted; shows Rename and Save icon buttons on hover.
* Files with unsaved changes are shown with an orange filename and save icon.
* A New Markdown File button appears on directory hover.
* A Recent files section is collapsible at the top of the tree.

The hamburger icon at the top-left of the header toggles the file tree open and closed; the open/closed state persists to localStorage.

## Outline Panel

The Outline panel lists headings from the active Markdown content. It opens from the header Outline icon as a Drawer, or can be pinned to the right aside. Headings can be filtered with the search field inside the panel.

## Settings

The Settings popover (gear icon in the header) provides:

* **Accent**: Four circular color swatches — Blue (default), Red, Purple, and Slate. Clicking a swatch switches the accent immediately; the selected swatch shows an outline ring. The choice persists to localStorage and rebuilds the Mantine theme without a page reload.
* **Theme**: System / Light / Dark segmented control. Mantine applies the preference immediately and stores it.
* **Autosave**: On / Off toggle.

## Empty State

When no file is selected, the workspace shows: `Choose or create a Markdown file.`

The empty state is intentionally plain because this is a tool surface, not a marketing page.

## Accessibility

Current accessibility practices include:

* Tooltip labels on all icon-only controls.
* `aria-label` on all action icons including Save and Git.
* `aria-disabled` on non-Markdown file options in the combobox.
* `aria-label` on the orange dirty dot beside the pill ("Unsaved changes").
* Keyboard-accessible pill, combobox, and panel controls.
* Non-color text labels for dirty ("Unsaved") and saved ("Saved") state.

## Known UX Gaps

* The right aside column is fixed at 300 px; drag-to-resize is not yet implemented.
* Save conflict responses are not yet routed into the visible conflict resolution component.
* The custom local asset-copy flow is not yet connected to the rich editor image action.
* No project-wide full-text search, broken-link report, or multi-document tab management.