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)

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)

projects: Signal<Project[]>              // All projects
currentProject: Signal<Project | null>   // Selected project

// Actions
setCurrentProject(id)
refreshProjects()

Team State (state/team.ts)

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

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

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

endpoints.tokens.drift(projectId)          // GET /api/projects/:id/token-drift
endpoints.tokens.recordDrift(projectId, data) // POST /api/projects/:id/token-drift

ESRE Endpoints (QA)

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

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

endpoints.cache.clear()                    // POST /api/cache/clear
endpoints.cache.purge()                    // DELETE /api/cache

Audit Endpoints

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

endpoints.claude.chat(message, projectId?, context?) // POST /api/claude/chat

MCP Endpoints

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

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)

--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)

--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

--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

--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

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