ui-ux
Desktop UI/UX guidance for Watchdown's editor surface (Electron + CodeMirror): accessibility and keyboard support, contrast and dark mode, editor typography, animation and reduced-motion, color semantics for diff/authorship/conflict, and status/feedback. Plus project-specific guidance for the live presence and diff-attribution UI. Use when designing, building, or reviewing any editor UI — gutters, markers, author glyphs, highlights, the status bar, or conflict rendering.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ui-ux
- description
- Desktop UI/UX guidance for Watchdown's editor surface (Electron + CodeMirror): accessibility and keyboard support, contrast and dark mode, editor typography, animation and reduced-motion, color semantics for diff/authorship/conflict, and status/feedback. Plus project-specific guidance for the live presence and diff-attribution UI. Use when designing, building, or reviewing any editor UI — gutters, markers, author glyphs, highlights, the status bar, or conflict rendering.
03 SKILL.md 正文
UI/UX — Watchdown editor
Curated, desktop-focused UX reference for the Watchdown markdown editor. Distilled for an Electron + CodeMirror desktop app — not mobile. The defining UI is the editor surface plus the live presence / diff-attribution layer (gutter markers, author icons, change highlights, status bar, inline conflict rendering).
When to use
- Designing or building the editor UI, gutter, status bar, or any control.
- Implementing the presence / diff-attribution layer (changed-line markers, author glyphs, highlight-on-external-change, "Claude is editing…" status).
- Rendering the conflict state (inline markers, accept/keep affordances).
- Reviewing UI for accessibility, contrast, keyboard support, or visual consistency.
Skip
- Pure core / sync-engine logic (it has no UI — keep it that way).
- Backend, filesystem, or build/CI work.
This is desktop. Ignore mobile-only concerns (touch-target sizes, safe areas/notch, haptics, bottom nav, swipe gestures) unless a real touch surface is added later.
1. Accessibility & keyboard (CRITICAL)
- Keyboard-first: every action reachable without a mouse; Tab order matches visual order.
- Preserve visible focus rings (2–4px) on all interactive controls — never remove them.
- Respect editor/OS keyboard shortcuts; don't shadow standard ones.
aria-label(or equivalent) on icon-only controls, including the author/presence glyph.- Don't convey meaning by color alone — pair diff/authorship/conflict color with an icon, marker, or text so it survives color-blindness and high-contrast modes.
- Provide a text/tooltip equivalent for every gutter marker and author icon (e.g. "Changed by Claude · 2s ago").
- Announce live changes politely (
aria-live="polite") so external edits and status changes reach screen readers without stealing focus.
2. Contrast & dark mode (CRITICAL)
- Body/editor text ≥ 4.5:1; secondary text ≥ 3:1. Diff and marker colors ≥ 3:1 vs background.
- Design light and dark together; dark mode uses desaturated tonal variants, not inverted colors. Verify contrast per theme — don't assume light values carry over.
- Keep dividers, gutter markers, and interaction states visible in both themes.
- Drive all colors from semantic tokens (e.g.
--diff-added,--author-external,--conflict), never raw hex in components.
3. Editor typography
- Monospace for the editor buffer; consistent line-height (~1.5) for readability.
- Use
font-display: swap/optionaland reserve space to avoid layout shift on load. - Tabular figures for any aligned numeric UI (line numbers, timers).
- Don't truncate where wrapping is possible; if truncating, offer the full text on hover.
4. Animation & reduced-motion (MEDIUM)
- Micro-interactions 150–300ms; the brief highlight on an externally-changed region lands in this range — long enough to notice, short enough not to nag.
- Animate
transform/opacityonly; neverwidth/height/top/left(causes reflow/CLS). - Honor
prefers-reduced-motion: replace highlight fades/pulses with an instant, static marker. Motion must be optional, never required to perceive a change. - Animation should express cause→effect (a change appeared here), not decorate.
- Keep input/typing latency under ~100ms; never block typing during an animation.
5. Color semantics for diff / authorship / conflict
- Distinct, tokenized, accessible roles: added vs removed vs externally-changed vs conflicting. Each role = color and a non-color cue (gutter glyph, underline, icon).
- Author attribution needs a stable per-author color + a labeled icon; the external (e.g. Claude) author glyph is an SVG icon, not an emoji (emoji render inconsistently and can't be themed via tokens).
- Conflict regions must be unmistakable and legible in both themes; pair the color with clear inline structure, not just a background tint.
6. Feedback & status
- The status bar is the primary feedback channel: reflect clean / dirty / conflict and presence ("Claude is editing…" vs "Claude idle") promptly and unambiguously.
- Show progress for anything over ~300ms; prefer a calm indicator over a blocking spinner.
- Destructive or lossy actions (discarding unsaved edits, overwriting on conflict) require confirmation and, where possible, undo.
- Empty/idle states should explain, not show a blank surface.
7. Layout & polish
- One consistent icon set (stroke width, corner radius); SVG/vector only — no raster, no emoji.
- Consistent spacing rhythm (4/8px scale) and a defined z-index scale (editor < gutter overlays < tooltips < modals).
- Press/hover/active/disabled states visually distinct without shifting layout bounds.
- One primary action per surface; secondary actions visually subordinate.
Pre-delivery checklist (desktop)
- [ ] Fully keyboard operable; focus order logical; focus rings visible.
- [ ] Text ≥ 4.5:1, markers/diff ≥ 3:1 — verified in light and dark.
- [ ] No color-only meaning — every diff/author/conflict cue has a non-color signal.
- [ ]
prefers-reduced-motionrespected (highlights degrade to static markers). - [ ] Author/presence glyphs are SVG icons with accessible labels and tooltips.
- [ ] Status bar correctly reflects clean / dirty / conflict and presence.
- [ ] No layout shift from change highlights or state transitions (transform/opacity only).
- [ ] Colors come from semantic tokens, not inline hex.
Adapted (desktop-only subset) from ui-ux-pro-max by Next Level Builder, MIT License. The original is a mobile/React-Native design-system tool with a Python search CLI and a large data corpus; this is a trimmed, static, desktop-editor-focused reference with no scripts or bundled data.
04 同仓库更多 Skills
release-process
How Watchdown versions and ships releases via release-please — squash-merge rules, the release PR gate, tag/installer build, and the RELEASE_PLEASE_PAT caveat. Use when merging PRs, cutting a release, or touching versioning.
demo-capture
How to capture the real running Watchdown window on Windows for screenshots and demo GIFs (README hero, release assets), and how to script a live-external-edit-sync GIF. Covers the capture method that actually works (PrintWindow + PW_RENDERFULLCONTENT + SetProcessDPIAware), why capturePage and plain screen-grabs fail, and the ImageMagick assembly recipe. Use whenever producing a screenshot/GIF of the app, or when a capture comes out blank, half-cropped, frameless, or from the wrong desktop.
ui-ux
Use when designing, building, or reviewing Watchdown's editor UI, including presence, attribution, status, and conflicts.
release-process
Use when merging Watchdown PRs, cutting a release, or changing versioning.
demo-capture
Use when capturing a screenshot or demo GIF of Watchdown on Windows, or troubleshooting a failed capture.