master-ai/UI-DESIGN-GUIDE.md

Product OS - UI Shell Design Guide

🎨 Design Customization Map

Quick Reference: Where to Change What

What You Want to Change	File to Edit	Line/Section
Colors	packages/monaco/data/monaco-themes/vscode/dark_vs.json	All colors
Fonts	packages/core/src/browser/style/index.css	Lines 40-62
Panel Sizes	packages/core/src/browser/shell/application-shell.ts	Lines 2269-2288
Layout Structure	packages/core/src/browser/shell/application-shell.ts	Lines 188-220
Borders & Spacing	packages/core/src/browser/style/index.css	Lines 24-76

---

1. COLOR CUSTOMIZATION

File: packages/monaco/data/monaco-themes/vscode/dark_vs.json

{
  "colors": {
    "editor.background": "#1E1E1E",              // Main editor area
    "editor.foreground": "#D4D4D4",              // Text color
    
    // SIDEBAR
    "sideBar.background": "#252526",             // Left/right sidebar background
    "sideBarTitle.foreground": "#BBBBBB",        // Sidebar titles
    
    // ACTIVITY BAR (left icon strip)
    "activityBar.background": "#333333",         // Activity bar background
    "activityBarBadge.background": "#007ACC",    // Badge colors (notifications)
    
    // PANELS (bottom area)
    "panel.background": "#1E1E1E",               // Bottom panel (terminal, etc)
    "panel.border": "#454545",                   // Panel borders
    
    // TABS
    "tab.activeBackground": "#1E1E1E",           // Active tab
    "tab.inactiveBackground": "#2D2D2D",         // Inactive tabs
    "tab.activeForeground": "#FFFFFF",           // Active tab text
    
    // MENU
    "menu.background": "#252526",                // Menu background
    "menu.foreground": "#CCCCCC",                // Menu text
    
    // STATUS BAR (bottom)
    "statusBar.background": "#007ACC",           // Status bar background
    "statusBar.foreground": "#FFFFFF",           // Status bar text
    
    // BUTTONS
    "button.background": "#0E639C",              // Button background
    "button.foreground": "#FFFFFF",              // Button text
    
    // INPUTS
    "input.background": "#3C3C3C",               // Input fields
    "input.foreground": "#CCCCCC",               // Input text
    "input.border": "#454545",                   // Input borders
  }
}

---

2. TYPOGRAPHY

File: packages/core/src/browser/style/index.css

:root {
    /* UI Font (menus, buttons, labels) */
    --theia-ui-font-size1: 13px;                           /* Base size */
    --theia-ui-font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
    
    /* Code Font (editor, terminal) */
    --theia-code-font-size: 13px;
    --theia-code-font-family: Menlo, Monaco, Consolas, "Droid Sans Mono";
    
    /* Change to your preferred fonts: */
    /* --theia-ui-font-family: "Inter", "SF Pro", sans-serif; */
    /* --theia-code-font-family: "JetBrains Mono", "Fira Code", monospace; */
}

---

3. SPACING & LAYOUT

File: packages/core/src/browser/style/index.css

:root {
    --theia-ui-padding: 6px;              /* General padding */
    --theia-border-width: 1px;            /* Border thickness */
    --theia-panel-border-width: 1px;      /* Panel borders */
    --theia-icon-size: 16px;              /* Icon size */
}

File: packages/core/src/browser/shell/application-shell.ts

// Panel size ratios (line ~2269)
export const DEFAULT_OPTIONS = {
    bottomPanel: {
        initialSizeRatio: 0.382  // 38.2% of window height
    },
    leftPanel: {
        initialSizeRatio: 0.191  // 19.1% of window width
    },
    rightPanel: {
        initialSizeRatio: 0.191  // 19.1% of window width
    }
}

---

4. QUICK DESIGN CHANGES - Copy & Paste

A. Modern Dark Blue Theme

File: packages/monaco/data/monaco-themes/vscode/dark_vs.json

{
  "colors": {
    "editor.background": "#0D1117",
    "sideBar.background": "#161B22",
    "activityBar.background": "#010409",
    "activityBarBadge.background": "#1F6FEB",
    "statusBar.background": "#1F6FEB",
    "panel.background": "#0D1117",
    "tab.activeBackground": "#0D1117",
    "tab.inactiveBackground": "#161B22"
  }
}

B. Increase Font Sizes

File: packages/core/src/browser/style/index.css

:root {
    --theia-ui-font-size1: 15px;     /* Was 13px */
    --theia-code-font-size: 15px;    /* Was 13px */
}

C. Wider Sidebars

File: packages/core/src/browser/shell/application-shell.ts

leftPanel: {
    initialSizeRatio: 0.25  // 25% instead of 19.1%
},
rightPanel: {
    initialSizeRatio: 0.25  // 25% instead of 19.1%
}

D. Smaller Bottom Panel

bottomPanel: {
    initialSizeRatio: 0.30  // 30% instead of 38.2%
}

---

5. PRODUCT OS BRANDING

Custom Colors for Product OS

{
  "colors": {
    // Google Cloud inspired
    "activityBarBadge.background": "#4285F4",     // Google Blue
    "statusBar.background": "#34A853",            // Google Green
    "button.background": "#4285F4",
    
    // Dark background
    "editor.background": "#121212",
    "sideBar.background": "#1E1E1E",
    "activityBar.background": "#0A0A0A",
  }
}

---

🚀 Testing Your Changes

Development Workflow:

1. Edit design files (CSS, JSON, TypeScript)
2. Rebuild:

   cd /Users/markhenderson/Cursor\ Projects/master-ai/theia
   npm run build:electron
   

3. Test:

   npm run start:electron
   

4. See changes immediately!

Watch Mode (auto-rebuild):

npm run watch:electron

---

📁 File Structure Summary

theia/
├── packages/
│   ├── core/src/browser/
│   │   ├── style/
│   │   │   └── index.css                 ← Typography, spacing, borders
│   │   └── shell/
│   │       └── application-shell.ts      ← Panel sizes, layout structure
│   └── monaco/data/monaco-themes/vscode/
│       └── dark_vs.json                  ← All colors
└── examples/electron/
    ├── package.json                      ← App name, branding
    └── resources/                        ← Icon, splash screen

---

🎯 Next Steps for Product OS Design

1. Lock dark theme (remove light theme option)
2. Custom color palette (Google Cloud colors)
3. Simplify UI (hide developer-focused elements)
4. Custom panels (replace File Explorer with Product sections)
5. Branding (logo, splash screen, app icon)

---

💡 Pro Tips

• CSS Variables are your friend - change one variable, affects everywhere
• Hot reload: Changes to CSS show immediately with watch mode
• Theme files: JSON files control all colors - easy to swap themes
• Test often: Build and test frequently to see visual changes