feat: Rebuild admin-ui with Preact + Signals
Some checks failed
DSS Project Analysis / dss-context-update (push) Has been cancelled
Some checks failed
DSS Project Analysis / dss-context-update (push) Has been cancelled
Complete rebuild of the admin-ui using Preact + Signals for a lightweight, reactive framework. Features include: - Team-centric workdesks (UI, UX, QA, Admin) - Comprehensive API client with 150+ DSS backend endpoints - Dark mode with system preference detection - Keyboard shortcuts and command palette - AI chat sidebar with Claude integration - Toast notifications system - Export/import functionality for project backup - TypeScript throughout with full type coverage Bundle size: ~66KB main (21KB gzipped), ~5KB framework overhead 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
339
admin-ui/AI-REFERENCE.md
Normal file
339
admin-ui/AI-REFERENCE.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user