`DW-Agents/dw-agents/THEME_MANAGER_GUIDE.md`

402 lines
# DW-Agents Theme Manager Guide
## Modern Minimalist Theme - Implementation Guide

**Version:** 1.0
**Theme:** Modern Minimalist
**Status:** Default for all new web viewers

---

## Overview

The DW-Agents Theme Manager provides a consistent, professional design system across all agents and web viewers. The **Modern Minimalist** theme is now the default standard for all new implementations.

### Key Features

- Clean, professional color palette
- Responsive design utilities
- Pre-built components (buttons, cards, badges)
- Consistent typography scale
- Generous spacing and modern shadows
- CSS variables for easy customization

---

## Quick Start

### For New Web Viewers (Recommended)

Use the `getThemedPageWrapper` function to automatically apply the theme:

```typescript
import express from 'express';
const { getThemedPageWrapper } = require('../shared-ui-components.js');

const app = express();
const PORT = 7XXX;

app.get('/', (req, res) => {
  const content = `
    <div class="card">
      <h2>Welcome to My Agent</h2>
      <p class="text-secondary">Your content goes here.</p>
      <button class="btn-primary">Take Action</button>
    </div>
  `;

  res.send(getThemedPageWrapper('My Agent Name', PORT, content));
});

app.listen(PORT, () => {
  console.log(`Agent running on port ${PORT}`);
});
```

That's it! Your agent now has:
- Modern minimalist theme applied
- Universal header with chat and refresh
- All utility classes available
- Responsive design built-in

---

## Manual Implementation

If you need more control, you can manually include the theme:

```typescript
const { getThemeStyles, getUniversalHeader } = require('../shared-ui-components.js');

app.get('/', (req, res) => {
  res.send(`
    <!DOCTYPE html>
    <html>
    <head>
      <title>My Agent</title>
      ${getThemeStyles('modern-minimalist')}
    </head>
    <body>
      ${getUniversalHeader('My Agent', PORT, 5)}

      <div style="padding: 1.5rem;">
        <!-- Your content here -->
      </div>
    </body>
    </html>
  `);
});
```

---

## Available Utility Classes

### Buttons

```html
<button class="btn-primary">Primary Action</button>
<button class="btn-secondary">Secondary Action</button>
```

### Cards

```html
<div class="card">
  <h3>Card Title</h3>
  <p>Card content goes here.</p>
</div>
```

### Badges

```html
<span class="badge badge-success">Success</span>
<span class="badge badge-warning">Warning</span>
<span class="badge badge-error">Error</span>
<span class="badge badge-info">Info</span>
```

### Grid Layouts

```html
<div class="grid grid-2">
  <div class="card">Column 1</div>
  <div class="card">Column 2</div>
</div>

<div class="grid grid-3">
  <div class="card">Column 1</div>
  <div class="card">Column 2</div>
  <div class="card">Column 3</div>
</div>
```

### Typography

```html
<h1>Heading 1 (30px)</h1>
<h2>Heading 2 (24px)</h2>
<h3>Heading 3 (20px)</h3>
<h4>Heading 4 (18px)</h4>

<p class="text-primary">Primary colored text</p>
<p class="text-secondary">Secondary colored text</p>
<p class="text-muted">Muted/tertiary text</p>
```

---

## Color Palette

### Primary Colors

- **Primary**: `#2563eb` - Modern blue for primary actions
- **Secondary**: `#7c3aed` - Elegant purple for secondary elements
- **Accent**: `#06b6d4` - Cyan for accents and highlights

### Semantic Colors

- **Success**: `#10b981` - Green for success states
- **Warning**: `#f59e0b` - Orange for warnings
- **Error**: `#ef4444` - Red for errors
- **Info**: `#3b82f6` - Blue for informational messages

### Neutral Colors

- **Neutral 50-900**: Gray scale from lightest to darkest
- **Background**: `#ffffff` - Default white background
- **Background Alt**: `#f8fafc` - Alternative light gray background

---

## Using CSS Variables

The theme provides CSS variables for all design tokens:

```css
.my-custom-component {
  background: var(--color-primary);
  color: var(--color-text-inverse);
  padding: var(--spacing-lg);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-md);
  font-size: var(--font-size-base);
  transition: var(--transition-base);
}

.my-custom-component:hover {
  background: var(--color-primary-dark);
  box-shadow: var(--shadow-lg);
}
```

---

## Accessing Theme via API

The UI Manager agent (Port 7240) provides theme access via API:

### Get Theme Object

```bash
GET http://45.61.58.125:7240/api/theme
```

Returns complete theme configuration as JSON.

### Get Theme CSS

```bash
GET http://45.61.58.125:7240/api/theme/css
```

Returns ready-to-use CSS with all theme styles.

### Get Theme Config

```bash
GET http://45.61.58.125:7240/api/theme/config
```

Returns theme configuration for programmatic use.

---

## Direct Theme Manager Usage

For advanced use cases, import the theme manager directly:

```typescript
const { getTheme, generateCSSVariables } = require('../theme-manager.js');

// Get theme object
const theme = getTheme('modern-minimalist');

// Access specific values
const primaryColor = theme.colors.primary;  // #2563eb
const largePadding = theme.spacing.lg;      // 1.5rem
const cardBorder = theme.borderRadius.lg;   // 0.75rem

// Generate CSS variables
const cssVars = generateCSSVariables('modern-minimalist');
```

---

## Component Examples

### Dashboard Header

```html
<div class="header">
  <h1>Agent Dashboard</h1>
  <p>Real-time monitoring and management</p>
</div>
```

### Status Cards Grid

```html
<div class="grid grid-3">
  <div class="card">
    <h3>Total Orders</h3>
    <p style="font-size: 2rem; font-weight: 600; color: var(--color-primary);">
      1,234
    </p>
    <span class="badge badge-success">+12% this month</span>
  </div>

  <div class="card">
    <h3>Revenue</h3>
    <p style="font-size: 2rem; font-weight: 600; color: var(--color-success);">
      $45,678
    </p>
    <span class="badge badge-info">On track</span>
  </div>

  <div class="card">
    <h3>Issues</h3>
    <p style="font-size: 2rem; font-weight: 600; color: var(--color-error);">
      3
    </p>
    <span class="badge badge-error">Needs attention</span>
  </div>
</div>
```

### Action List

```html
<div class="card">
  <h3>Recent Actions</h3>
  <ul style="list-style: none; padding: 0;">
    <li style="padding: 0.75rem 0; border-bottom: 1px solid var(--color-neutral-200);">
      <div style="display: flex; justify-content: space-between; align-items: center;">
        <span>Order #1234 processed</span>
        <span class="badge badge-success">Complete</span>
      </div>
    </li>
    <li style="padding: 0.75rem 0; border-bottom: 1px solid var(--color-neutral-200);">
      <div style="display: flex; justify-content: space-between; align-items: center;">
        <span>Payment received</span>
        <span class="badge badge-info">Verified</span>
      </div>
    </li>
  </ul>
</div>
```

---

## Responsive Design

All components are mobile-friendly by default. Grids automatically collapse to single column on mobile:

```html
<!-- Desktop: 4 columns, Mobile: 1 column -->
<div class="grid grid-4">
  <div class="card">Item 1</div>
  <div class="card">Item 2</div>
  <div class="card">Item 3</div>
  <div class="card">Item 4</div>
</div>
```

---

## Best Practices

### 1. Always Use Theme Utilities

❌ **Don't** hardcode colors:
```html
<button style="background: #667eea; color: white;">Click Me</button>
```

✅ **Do** use utility classes:
```html
<button class="btn-primary">Click Me</button>
```

### 2. Use CSS Variables for Custom Styles

❌ **Don't** hardcode values:
```css
.custom { padding: 20px; color: #2c3e50; }
```

✅ **Do** use CSS variables:
```css
.custom { padding: var(--spacing-base); color: var(--color-dark); }
```

### 3. Leverage Pre-built Components

Use `.card`, `.btn-primary`, `.badge` classes instead of creating custom styles from scratch.

### 4. Test Responsiveness

Always test your layouts on different screen sizes. The theme handles mobile breakpoints automatically.

---

## Migration Guide

### Updating Existing Agents

To update an existing agent to use the modern minimalist theme:

1. **Import theme utilities**:
   ```typescript
   const { getThemedPageWrapper } = require('../shared-ui-components.js');
   ```

2. **Replace your existing HTML wrapper** with `getThemedPageWrapper()`

3. **Update inline styles** to use utility classes:
   - Replace custom buttons with `.btn-primary` / `.btn-secondary`
   - Replace custom cards with `.card`
   - Replace status indicators with `.badge-*` classes

4. **Test and refine** your layouts

---

## Support

- **UI Manager Dashboard**: http://45.61.58.125:7240
- **Theme Manager Tab**: View live examples and documentation
- **API Documentation**: Available in UI Manager Functions tab

---

## Files

- **Theme Configuration**: `/root/DW-Agents/theme-manager.js`
- **Shared UI Components**: `/root/DW-Agents/shared-ui-components.js`
- **UI Manager Agent**: `/root/DW-Agents/agent-ui-manager/ui-manager-agent.ts`

---

**Note**: This theme is now the default standard for all new web viewers. For consistency, please use `getThemedPageWrapper()` when creating new agent interfaces.