botserver/web/desktop/QUICKSTART.md

Quick Start Guide - General Bots Desktop

Get up and running with General Bots Desktop in 5 minutes!

🚀 Installation

Option 1: Using Python (Recommended)

cd botserver/web/desktop
python3 -m http.server 8000

Open http://localhost:8000 in your browser.

Option 2: Using Node.js

cd botserver/web/desktop
npx http-server -p 8000

Option 3: Using PHP

cd botserver/web/desktop
php -S localhost:8000

📂 Project Structure at a Glance

desktop/
├── index.html              # Main entry point
├── css/app.css             # Core styles + theme system
├── js/
│   ├── theme-manager.js    # Theme switching
│   └── layout.js           # Section loading
├── public/themes/          # 19+ theme files
├── chat/                   # Chat module
├── drive/                  # Drive module
├── tasks/                  # Tasks module
└── mail/                   # Mail module

🎨 Try Different Themes

1. Launch the application
2. Click the theme dropdown in the header
3. Select any theme (try "Cyberpunk" or "Retrowave"!)
4. Theme is saved automatically

⌨️ Essential Keyboard Shortcuts

• Alt + 1 → Chat
• Alt + 2 → Drive
• Alt + 3 → Tasks
• Alt + 4 → Mail
• Esc → Close menus

🛠️ Create Your First Theme

Step 1: Create Theme File

Create public/themes/myawesome.css:

:root {
  /* Base colors (HSL format: H S% L%) */
  --background: 230 35% 10%;          /* Dark blue-gray */
  --foreground: 0 0% 95%;             /* Light text */
  
  /* Cards */
  --card: 230 35% 15%;
  --card-foreground: 0 0% 95%;
  
  /* Primary accent (your brand color) */
  --primary: 280 90% 60%;             /* Purple */
  --primary-foreground: 0 0% 100%;
  
  /* Secondary */
  --secondary: 230 35% 20%;
  --secondary-foreground: 0 0% 95%;
  
  /* Muted elements */
  --muted: 230 35% 25%;
  --muted-foreground: 230 15% 60%;
  
  /* Accent highlights */
  --accent: 340 90% 60%;              /* Pink */
  --accent-foreground: 0 0% 100%;
  
  /* Error states */
  --destructive: 0 85% 60%;
  --destructive-foreground: 0 0% 98%;
  
  /* Borders and inputs */
  --border: 230 35% 20%;
  --input: 230 35% 20%;
  --ring: 280 90% 60%;
  
  /* Border radius */
  --radius: 0.5rem;
  
  /* Charts */
  --chart-1: 280 90% 60%;
  --chart-2: 340 90% 60%;
  --chart-3: 200 90% 60%;
  --chart-4: 140 90% 60%;
  --chart-5: 40 90% 60%;
}

Step 2: Register Your Theme

Edit js/theme-manager.js, add to the themes array:

{ id: "myawesome", name: "✨ My Awesome", file: "myawesome.css" }

Step 3: Test It!

1. Reload the application
2. Open theme dropdown
3. Select "✨ My Awesome"
4. Enjoy your custom theme!

🧩 Add a New Module

Step 1: Create Module Files

Create directory: mymodule/

mymodule/mymodule.html:

<div class="mymodule-layout">
  <h1>My Module</h1>
  <p>Hello from my custom module!</p>
</div>

mymodule/mymodule.css:

.mymodule-layout {
  padding: var(--space-xl);
  max-width: 1200px;
  margin: 0 auto;
  padding-top: calc(var(--header-height) + var(--space-xl));
}

.mymodule-layout h1 {
  color: var(--text-primary);
  margin-bottom: var(--space-lg);
}

mymodule/mymodule.js:

console.log('My Module loaded!');

// Initialize your module here

Step 2: Register Module

Edit js/layout.js, add to sections object:

const sections = {
  drive: "drive/drive.html",
  tasks: "tasks/tasks.html",
  mail: "mail/mail.html",
  chat: "chat/chat.html",
  mymodule: "mymodule/mymodule.html"  // Add this
};

Step 3: Add to Apps Menu

Edit index.html, add to .app-grid:

<a class="app-item" href="#mymodule" data-section="mymodule" role="menuitem">
  <div class="app-icon" aria-hidden="true">🚀</div>
  <span>My Module</span>
</a>

Step 4: Test Your Module

1. Reload application
2. Click apps menu (9 dots icon)
3. Click "My Module"
4. See your module load!

🎯 Common Tasks

Change Logo

Edit index.html, update logo-icon:

<div class="logo-icon" style="background-image: url('path/to/logo.svg')"></div>

Change App Title

Edit index.html:

<title>My Awesome App</title>
<span class="logo-text">My Awesome App</span>

Customize Colors in Code

.my-component {
  /* Use theme variables */
  background: var(--primary-bg);
  color: var(--text-primary);
  border: 1px solid var(--border-color);
}

.my-button {
  background: var(--accent-color);
  color: hsl(var(--primary-foreground));
}

.my-button:hover {
  background: var(--accent-hover);
}

Add Custom Styles

Create css/custom.css:

.my-custom-class {
  /* Your styles using theme variables */
  padding: var(--space-lg);
  border-radius: var(--radius-lg);
  box-shadow: var(--shadow-md);
}

Link it in index.html:

<link rel="stylesheet" href="css/app.css" />
<link rel="stylesheet" href="css/custom.css" />

🐛 Troubleshooting

Theme Not Loading?

1. Check browser console (F12)
2. Verify file exists in public/themes/
3. Check CSS syntax (no commas in HSL values!)
4. Clear browser cache (Ctrl+Shift+R)

Module Not Showing?

1. Check all three files exist (HTML, CSS, JS)
2. Verify registration in layout.js
3. Check browser console for errors
4. Ensure file paths are correct

Colors Look Wrong?

HSL format is: H S% L% (no commas!)

Wrong: hsl(280, 90%, 60%)
Right: 280 90% 60%

Can't Switch Sections?

1. Check console for JavaScript errors
2. Verify window.switchSection is defined
3. Try reloading the page
4. Clear localStorage

📚 Next Steps

• Themes: Read THEMES.md for advanced theming
• Components: Check COMPONENTS.md for UI components
• Full Docs: See README.md for complete documentation

💡 Tips & Tricks

Debug Mode

Open browser console and enable verbose logging:

localStorage.setItem('debug', 'true');
location.reload();

Test All Themes Quickly

// Run in browser console
const themes = ThemeManager.getAvailableThemes();
themes.forEach((t, i) => {
  setTimeout(() => ThemeManager.loadTheme(t.id), i * 2000);
});

HSL Color Picker

Use online tools:

• https://hslpicker.com/
• https://coolors.co/
• Chrome DevTools color picker

Accessibility Check

// Check contrast ratios in console
const bg = getComputedStyle(document.body).backgroundColor;
const fg = getComputedStyle(document.body).color;
console.log('Background:', bg);
console.log('Foreground:', fg);

🎓 Learning Resources

• HSL Colors: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl
• CSS Variables: https://developer.mozilla.org/en-US/docs/Web/CSS/--*
• Accessibility: https://www.w3.org/WAI/WCAG21/quickref/
• Alpine.js: https://alpinejs.dev/ (used in Drive/Tasks/Mail)

🤝 Get Help

• Check documentation files in this directory
• Review browser console for errors
• Test with different browsers
• Try disabling browser extensions

✅ Checklist for New Features

• Works with all themes
• Responsive on mobile
• Keyboard navigation works
• ARIA labels present
• Uses theme variables
• No console errors
• Documented in code
• Tested in multiple browsers

---

Happy Building! 🚀

Need more help? See README.md, THEMES.md, and COMPONENTS.md