dss/admin-ui/AI-REFERENCE.md

# DSS Admin UI - AI Reference Documentation

## Overview
The DSS Admin UI is a Preact + Signals application that provides a team-centric dashboard for managing design system operations. It connects to the DSS backend API (FastAPI server running on port 8002).

## Technology Stack
- **Framework**: Preact 10.x (~3KB)
- **State Management**: @preact/signals (~2KB)
- **Build**: Vite 5.x
- **Language**: TypeScript
- **Routing**: Hash-based (#routes)
- **Styling**: CSS with design tokens

## Architecture

### Directory Structure
```
admin-ui/src/
├── main.tsx              # Entry point
├── App.tsx               # Root component with theme, shortcuts, toasts
├── state/                # Centralized state (signals)
│   ├── index.ts          # Re-exports all state
│   ├── app.ts            # Theme, panels, notifications
│   ├── project.ts        # Project list, current project
│   └── team.ts           # Teams, tools, configs
├── api/
│   ├── client.ts         # API client with all endpoints
│   └── types.ts          # TypeScript interfaces
├── components/
│   ├── base/             # Button, Card, Input, Badge, Spinner
│   ├── layout/           # Shell, Header, Sidebar, Panel, ChatSidebar
│   └── shared/           # CommandPalette, Toast
├── workdesks/            # Team-specific views
│   ├── UIWorkdesk.tsx    # Figma extraction, code generation
│   ├── UXWorkdesk.tsx    # Token list, Figma files
│   ├── QAWorkdesk.tsx    # ESRE editor, console viewer
│   └── AdminWorkdesk.tsx # Settings, projects, audit log
├── hooks/
│   └── useKeyboard.ts    # Global keyboard shortcuts
└── styles/
    ├── tokens.css        # Design tokens (light + dark)
    └── base.css          # Reset and base styles
```

## State Signals

### App State (`state/app.ts`)
```typescript
theme: Signal<'light' | 'dark' | 'auto'>  // Current theme
sidebarOpen: Signal<boolean>               // Sidebar visibility
chatSidebarOpen: Signal<boolean>           // AI chat visibility
commandPaletteOpen: Signal<boolean>        // Command palette visibility
activePanel: Signal<PanelId>               // Bottom panel tab
notifications: Signal<Notification[]>      // Toast notifications

// Actions
setTheme(theme)
toggleChatSidebar()
toggleCommandPalette()
addNotification(type, title, message)
dismissNotification(id)
```

### Project State (`state/project.ts`)
```typescript
projects: Signal<Project[]>              // All projects
currentProject: Signal<Project | null>   // Selected project

// Actions
setCurrentProject(id)
refreshProjects()
```

### Team State (`state/team.ts`)
```typescript
activeTeam: Signal<'ui' | 'ux' | 'qa' | 'admin'>  // Current team
teamConfig: Computed<TeamConfig>                   // Team's tools, panels, etc.

// Actions
setActiveTeam(team)
```

## API Endpoints (`api/client.ts`)

### Project Endpoints
```typescript
endpoints.projects.list(status?)           // GET /api/projects
endpoints.projects.get(id)                 // GET /api/projects/:id
endpoints.projects.create(data)            // POST /api/projects
endpoints.projects.update(id, data)        // PUT /api/projects/:id
endpoints.projects.delete(id)              // DELETE /api/projects/:id
endpoints.projects.config(id)              // GET /api/projects/:id/config
endpoints.projects.components(id)          // GET /api/projects/:id/components
endpoints.projects.figmaFiles(id)          // GET /api/projects/:id/figma-files
endpoints.projects.addFigmaFile(id, data)  // POST /api/projects/:id/figma-files
endpoints.projects.syncFigmaFile(id, fileId) // PUT /api/projects/:id/figma-files/:fileId/sync
```

### Figma Endpoints
```typescript
endpoints.figma.health()                   // GET /api/figma/health
endpoints.figma.extractVariables(fileKey, nodeId?)  // POST /api/figma/extract-variables
endpoints.figma.extractComponents(fileKey, nodeId?) // POST /api/figma/extract-components
endpoints.figma.extractStyles(fileKey, nodeId?)     // POST /api/figma/extract-styles
endpoints.figma.generateCode(componentDef, framework?) // POST /api/figma/generate-code
```

### Token Endpoints
```typescript
endpoints.tokens.drift(projectId)          // GET /api/projects/:id/token-drift
endpoints.tokens.recordDrift(projectId, data) // POST /api/projects/:id/token-drift
```

### ESRE Endpoints (QA)
```typescript
endpoints.esre.list(projectId)             // GET /api/projects/:id/esre
endpoints.esre.create(projectId, data)     // POST /api/projects/:id/esre
endpoints.esre.update(projectId, esreId, data) // PUT /api/projects/:id/esre/:esreId
endpoints.esre.delete(projectId, esreId)   // DELETE /api/projects/:id/esre/:esreId
```

### System Endpoints
```typescript
endpoints.system.health()                  // GET /api/health
endpoints.system.config()                  // GET /api/config
endpoints.system.updateConfig(data)        // PUT /api/config
endpoints.system.figmaConfig()             // GET /api/config/figma
endpoints.system.testFigma()               // POST /api/config/figma/test
```

### Cache Endpoints
```typescript
endpoints.cache.clear()                    // POST /api/cache/clear
endpoints.cache.purge()                    // DELETE /api/cache
```

### Audit Endpoints
```typescript
endpoints.audit.list(params?)              // GET /api/audit
endpoints.audit.stats()                    // GET /api/audit/stats
endpoints.audit.export(format)             // GET /api/audit/export?format=json|csv
```

### Claude AI Endpoints
```typescript
endpoints.claude.chat(message, projectId?, context?) // POST /api/claude/chat
```

### MCP Endpoints
```typescript
endpoints.mcp.tools()                      // GET /api/mcp/tools
endpoints.mcp.execute(name, params)        // POST /api/mcp/tools/:name/execute
endpoints.mcp.status()                     // GET /api/mcp/status
```

## Team Workdesks

### UI Team (`UIWorkdesk.tsx`)
**Purpose**: Component library & Figma sync

**Tools**:
- `dashboard` - Metrics: components count, token drift issues
- `figma-extraction` - Extract tokens from Figma using `endpoints.figma.extractVariables()`
- `figma-components` - Extract components using `endpoints.figma.extractComponents()`
- `code-generator` - Generate code using `endpoints.figma.generateCode()`
- `token-drift` - View drift using `endpoints.tokens.drift()`

### UX Team (`UXWorkdesk.tsx`)
**Purpose**: Design consistency & token validation

**Tools**:
- `dashboard` - Figma connection status, file sync status
- `token-list` - View tokens from Figma
- `figma-files` - Manage connected Figma files
- `figma-plugin` - Plugin installation info

### QA Team (`QAWorkdesk.tsx`)
**Purpose**: Testing, validation & quality

**Tools**:
- `dashboard` - Health score, ESRE definitions count
- `esre-editor` - Create/edit/delete ESRE definitions
- `console-viewer` - Browser console log capture
- `test-results` - View ESRE test results

### Admin (`AdminWorkdesk.tsx`)
**Purpose**: System configuration & management

**Tools**:
- `settings` - Server config, Figma token, Storybook URL
- `projects` - CRUD for projects
- `integrations` - External service connections
- `audit-log` - System activity with filtering/export
- `cache-management` - Clear/purge cache
- `health-monitor` - Service status with auto-refresh
- `export-import` - Project backup/restore

## Features

### Dark Mode
- Toggle via Header button or Command Palette
- Auto mode detects system preference
- Persisted to localStorage as `dss-theme`
- CSS variables in `[data-theme="dark"]` selector

### Keyboard Shortcuts
```
⌘K       - Open command palette
⌘/       - Toggle AI chat
⌘1       - Switch to UI team
⌘2       - Switch to UX team
⌘3       - Switch to QA team
⌘4       - Switch to Admin
Escape   - Close dialogs
```

### Command Palette
- Quick access to all teams, projects, and actions
- Fuzzy search through commands
- Keyboard navigation (↑↓ Enter Escape)

### AI Chat Sidebar
- Context-aware (passes current project/team)
- Quick actions for common prompts
- Displays tool calls and results
- Basic markdown formatting

### Toast Notifications
- Success, error, warning, info types
- Auto-dismiss for non-errors (5s)
- Manual dismiss available

### Export/Import
- Export project data as JSON archive
- Import with preview
- Progress indicators

## TypeScript Types (`api/types.ts`)

### Core Types
```typescript
interface Project {
  id: string;
  name: string;
  description?: string;
  path: string;
  status: 'active' | 'archived' | 'draft';
  components_count?: number;
  tokens_count?: number;
}

interface FigmaFile {
  id: string;
  name: string;
  file_key: string;
  status: 'pending' | 'synced' | 'error';
  last_synced?: string;
}

interface ESREDefinition {
  id: string;
  name: string;
  description?: string;
  type: 'visual' | 'behavioral' | 'accessibility';
  selector: string;
  expectations: Record<string, unknown>;
}

interface SystemHealth {
  status: 'healthy' | 'degraded' | 'unhealthy';
  services: { storage: string; mcp: string; figma: string };
  timestamp: string;
}

interface ChatResponse {
  message?: { role: string; content: string };
  tool_calls?: ToolCall[];
  tool_results?: ToolResult[];
}
```

## CSS Design Tokens

### Colors (Light Mode)
```css
--color-primary: hsl(220, 14%, 10%)
--color-background: hsl(0, 0%, 100%)
--color-surface-0: hsl(0, 0%, 100%)
--color-surface-1: hsl(220, 14%, 98%)
--color-border: hsl(220, 9%, 89%)
--color-success: hsl(142, 76%, 36%)
--color-error: hsl(0, 84%, 60%)
--color-warning: hsl(38, 92%, 50%)
```

### Colors (Dark Mode)
```css
--color-primary: hsl(220, 14%, 90%)
--color-background: hsl(220, 14%, 10%)
--color-surface-0: hsl(220, 14%, 10%)
--color-surface-1: hsl(220, 14%, 12%)
--color-border: hsl(220, 9%, 20%)
```

### Spacing
```css
--spacing-1: 0.25rem (4px)
--spacing-2: 0.5rem (8px)
--spacing-3: 0.75rem (12px)
--spacing-4: 1rem (16px)
--spacing-6: 1.5rem (24px)
--spacing-8: 2rem (32px)
```

### Typography
```css
--font-size-xs: 0.75rem
--font-size-sm: 0.875rem
--font-size-base: 1rem
--font-size-lg: 1.125rem
--font-weight-normal: 400
--font-weight-medium: 500
--font-weight-semibold: 600
--font-weight-bold: 700
```

## Build Commands

```bash
npm run dev      # Start dev server (port 5173)
npm run build    # TypeScript check + Vite build
npm run preview  # Preview production build
```

## Bundle Size
- Framework (Preact + Signals): ~5KB
- Main bundle: ~66KB gzipped ~21KB
- Total CSS: ~28KB gzipped ~5KB
- Lazy-loaded workdesks: ~10-18KB each