════════════════════════════════════════════════════════════════════════
  UI DESIGN
  Gnomad Webcanvas · docs/UI_DESIGN.md
════════════════════════════════════════════════════════════════════════

UI DESIGN — GNOMAD WEBCANVAS
============================

Version: 0.1.0-beta.2  
Last updated: June 2026

────────────────────────────────────────

DESIGN INTENT
-------------

Gnomad Webcanvas follows a GitHub-inspired editor aesthetic — familiar to developers, low distraction, high information density. The UI prioritizes code and preview over chrome. Three shell themes (dark, light, high contrast) adapt the entire app chrome, not just the Monaco editor.

────────────────────────────────────────

THEME SYSTEM
------------

The navbar Theme dropdown sets both Monaco and shell appearance:

  Monaco theme  |  Shell data-ui-theme  |  Description                                    
  vs-dark       |  dark                 |  Default — #0d1117 base, #161b22 panels         
  vs-light      |  light                |  Light gray/white chrome for bright environments
  hc-black      |  hc                   |  High contrast — white borders/text on black    

Implementation:

  • CSS variables defined in src/app.css per theme
  • Utility classes: .ui-bg-base, .ui-bg-panel, .ui-text-muted, etc.
  • App.tsx sets document.documentElement.dataset.uiTheme on theme change
  • Preference persisted via src/utils/preferences.ts → localStorage

────────────────────────────────────────

COLOR PALETTE (DARK THEME)
--------------------------

  Token             |  CSS variable      |  Dark value
  Base background   |  --ui-bg-base      |  #0d1117   
  Panel background  |  --ui-bg-panel     |  #161b22   
  Elevated surface  |  --ui-bg-elevated  |  #21262d   
  Border            |  --ui-border       |  #30363d   
  Text primary      |  --ui-text         |  #f0f6fc   
  Text muted        |  --ui-text-muted   |  #8b949e   

Light and high-contrast values are in the same file under [data-ui-theme='light'] and [data-ui-theme='hc'].

Pane accent colors

  Pane  |  Color   |  Purpose           
  HTML  |  Orange  |  Pane dot indicator
  CSS   |  Blue    |  Pane dot indicator
  JS    |  Yellow  |  Pane dot indicator

Defined in src/constants/editorConfig.ts as PANE_COLORS. Theme-independent.

────────────────────────────────────────

LAYOUT
------

  [code]
    ┌─────────────────────────────────────────────────────────────┐
    │ TopNavbar (shrink-0, h ~40px)                               │
    ├──────────────────────────┬──────────────────────────────────┤
    │ Editor panels (flex)     │ PreviewFrame (flex)              │
    │ react-resizable-panels   │ iframe + toolbar + console       │
    ├──────────────────────────┴──────────────────────────────────┤
    │ Floating tools bar (shrink-0, horizontal scroll)            │
    └─────────────────────────────────────────────────────────────┘

  • Vertical layout (default): Editors stacked left, preview right
  • Horizontal layout: Editors stacked top, preview bottom
  • Preview fullscreen: Hides editors and tools; preview only

────────────────────────────────────────

TYPOGRAPHY
----------

  Context          |  Font                                       
  UI chrome        |  system-ui, Tailwind defaults               
  Code editor      |  Monaco default (Consolas, Menlo, monospace)
  Preview content  |  User-controlled via CSS / font pairings    

Font pairings inject Google Fonts  into preview only — not the app shell.

────────────────────────────────────────

COMPONENTS
----------

  Component       |  Design notes                                                  
  TopNavbar       |  Compact icon + text buttons; theme selector; dropdown menus   
  PaneHeader      |  Colored dot + label; maximize on double-click                 
  ResizeHandle    |  4px drag target; themed border hover                          
  PreviewFrame    |  Toolbar with viewport chips, background toggle, console toggle
  ConsolePanel    |  Bottom drawer; monospace log entries with method color coding 
  FloatingTools   |  Inline controls; separated by vertical dividers               
  ShortcutsModal  |  Overlay table of keyboard shortcuts                           

────────────────────────────────────────

MONACO THEMES
-------------

  Theme          |  Value     |  Shell sync
  Dark           |  vs-dark   |  dark      
  Light          |  vs-light  |  light     
  High Contrast  |  hc-black  |  hc        

User-selectable from navbar; persisted in localStorage (liveview-preferences).

────────────────────────────────────────

PREVIEW CHROME
--------------

  Control           |  Visual                                
  Viewport presets  |  Pill buttons; active state highlighted
  Background cycle  |  Icon buttons: ☀ ☾ ▦                   
  Console           |  Toggle; badge when entries present    

Preview iframe border respects viewport preset width (centered when narrower than panel). Preview backgrounds are independent of shell theme.

────────────────────────────────────────

INTERACTION PATTERNS
--------------------

  Pattern              |  Implementation                                
  Dirty state          |  Window title * (desktop); no web indicator yet
  Confirm destructive  |  Reset project — click twice within 3 s        
  Toast                |  Share copied — 2 s fade                       
  Debounced preview    |  500 ms after last keystroke                   

────────────────────────────────────────

RESPONSIVE BEHAVIOR
-------------------

Primary target: desktop ≥800×500 (Tauri minimum). Web mode works on smaller screens but panel layout may require horizontal scroll on narrow viewports.

────────────────────────────────────────

FUTURE POLISH
-------------

  • [ ] Dedicated colorblind palette
  • [ ] Custom accent color picker
  • [ ] Compact navbar mode for small screens
  • [ ] Reduced motion preference

────────────────────────────────────────

Built with ❤️ by Gnomad Studio 🦙

════════════════════════════════════════════════════════════════════════
Built with ❤️ by Gnomad Studio 🦙
https://gnomadstudio.org
════════════════════════════════════════════════════════════════════════