🌐 English | Tiếng Việt

Desygn AI

AI-Powered Design Intelligence Platform — tự động audit UI/UX, sinh code từ design, và học hỏi từ mỗi dự án.

Mục lục

• Tổng quan
• Kiến trúc hệ thống
• Hệ thống Agent (v5)
• Agent Fleet v6
• Cấu trúc dự án
• Tính năng
• Cài đặt & Vận hành
• API Endpoints
• Thư viện Template
• Kiểm thử & Chất lượng
• Triển khai
• Cấu hình
• Tài liệu kỹ thuật
• Giấy phép

Tổng quan

Desygn AI là nền tảng trí tuệ thiết kế kết nối Figma với AI coding agents. Hệ thống gồm 3 surface chính:

Kiến trúc hệ thống

Tổng quan kiến trúc v5

┌─────────────────────────────────────────────────────────────────────────┐
│                         DESYGN AI PLATFORM v5                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                           │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐ │
│  │ Figma Plugin│   │ Web App     │   │ API Layer   │   │ Agent System│ │
│  │ (Sandbox)   │──▶│ (React+Vite)│──▶│ (Serverless)│──▶│ (Shannon v3)│ │
│  └──────┬──────┘   └──────┬──────┘   └──────┬──────┘   └──────┬──────┘ │
│         │                  │                  │                  │        │
│         ▼                  ▼                  ▼                  ▼        │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │                    INTELLIGENCE LAYER                                │ │
│  ├─────────────────────────────────────────────────────────────────────┤ │
│  │  Shannon Engine ─── GOAP Planner ─── Evidence Memory (HNSW)        │ │
│  │  PII Scanner ────── Usage Analytics ── Collaboration CRDT          │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
│         │                  │                  │                  │        │
│         ▼                  ▼                  ▼                  ▼        │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │                    UX CHECKLIST AUDITOR (v5)                         │ │
│  ├─────────────────────────────────────────────────────────────────────┤ │
│  │  AuditAgent → ScoreAgent → RecommendAgent → IssueWriter → CIGate  │ │
│  │  MemoryAgent (cross-project) ── LearningLoop (sigmoid decay)       │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
│                                                                           │
└─────────────────────────────────────────────────────────────────────────┘

Nguyên tắc kiến trúc

• Plugin sandbox: Không DOM, không fetch — chỉ Figma API
• UI iframe: Không figma.* — chỉ parent.postMessage
• Giao tiếp: Typed PluginMessage qua postMessage
• Scoring: Pure functions — không side effects, không Figma API
• Bảo mật: Sanitize tất cả prompt text, PII detection tự động
• State: useSyncExternalStore với localStorage persistence

Hệ thống Agent (v5)

Pipeline xử lý

Figma Plugin ──scan──▶ DesignAuditAgent ──▶ AccessibilityAgent
                            │                      │
                            ▼                      ▼
                       ScoreAgent ◄──── DesignSystemAgent
                            │
                            ▼
                    ┌───────┴───────┐
                    ▼               ▼
             FixPlannerAgent   RecommendAgent
                    │               │
                    ▼               ▼
             IssueWriterAgent   CIGate
             (GitHub Issues)    (Block deploy)
                    │               │
                    ▼               ▼
              PRAutomation     DeployGate
              (Draft PRs)     (Vercel/Slack)
                    │
                    ▼
              MemoryAgent
           (Learn + Persist)

Danh sách Agents

Self-Learning Loop

1. Agent đánh giá criterion → AuditResult
2. ScoreAgent calibrate bằng Bayesian + historical evidence
3. LearningLoop lưu vào Evidence Memory (HNSW vector search)
4. User feedback (agree/disagree/irrelevant) → điều chỉnh criterion weights
5. Sigmoid decay trên evidence chưa validate (knowledge half-life)
6. Audit tiếp theo sử dụng calibrated weights → scoring chính xác hơn

CI/CD Integration

• CIGate: Block deploy nếu audit score < threshold
• SARIF v2.1.0: Tương thích GitHub Code Scanning
• GitHub Actions: Template workflow tự động
• DeployGate: Vercel/Netlify blocking + Slack notifications

Agent Fleet v6

Architecture Decision Record: docs/architecture/AGENT_FLEET_V6.md

Hệ thống 22 agent / 8 fleet hoạt động tự chủ với worktree isolation, cost gating, và self-improvement loop.

Tổng quan Fleet

Self-Improvement Loop

User/Cron → HumanCommandAgent → SelfDiagnosticAgent → OrchestratorAgent
  → WorktreeRunner.create() → RefactorAgent/TestGenAgent → CodeFixAgent
  → SafetyGateAgent → DiffApplierAgent → RegressionGuardAgent
  → ConflictResolverAgent → FixApprovalUI → User Approve/Reject
  → SelfAuditAgent + BenchmarkAgent (health tracking)

Safety Guards

• Cost gate: $MAX_COST_USD budget per orchestration run
• Worktree isolation: All changes in git worktrees, main is read-only
• Secret detection: 7 regex patterns (API keys, AWS, GitHub PAT, OpenAI, JWT, private keys)
• Protected files: .env*, *.pem, credentials*, CI workflows, lock files
• Regression guard: Lint → build → test fail-fast (120s timeout per step)
• Conflict resolver: Same-region, adjacent, whole-file conflict detection
• User approval: Every code change requires explicit approve/reject via FixApprovalUI

Test Coverage

• 25 test files, 192 agent-specific tests — 100% module coverage
• E2E self-improvement pipeline test (diagnostic → refactor → diff → apply → verify)
• Pure reducer tests for FixApprovalUI state management

Cấu trúc dự án

desygn-ai/
├── api/                              # Vercel serverless functions
│   ├── chat.ts                       #   Groq AI chat endpoint
│   ├── generate-html.ts              #   HTML generation
│   ├── generate-screens.ts           #   Screen generation
│   ├── analyze-image.ts              #   Image analysis
│   └── lib/sanitize.ts               #   Input sanitization
│
├── plugin/                           # Figma plugin (sandbox)
│   ├── code.ts                       #   Entry point
│   ├── serializer.ts                 #   Node serialization (isMixed checks)
│   └── handlers/                     #   Auto-layout, fixes, profiles
│
├── shared/                           # Shared code (plugin + UI + web)
│   ├── types.ts                      #   SerializedNode, PluginMessage
│   ├── viewport.ts                   #   Viewport classification
│   └── designContext.ts              #   DesignContext types
│
├── ui/                               # Figma plugin React UI (iframe)
│   ├── App.tsx                       #   Root component
│   ├── components/                   #   38 UI components (CSS Modules)
│   ├── hooks/                        #   Custom React hooks
│   └── lib/                          #   Scanner, scoring, prompt gen
│
├── web/src/                          # Web workspace (Desygn AI)
│   ├── main.tsx                      #   App entry
│   ├── ai-layer/                     #   AI experiment orchestration
│   │   └── index.ts                  #     6 built-in experiments, A/B testing
│   ├── app-shell/                    #   Toast, theme, global config
│   ├── auth/                         #   Session controller + TTL watchdog
│   ├── chat-engine/                  #   AI chat + provider abstraction
│   ├── design-engine/                #   Design.md generation + validation
│   ├── workspace-store/              #   Reactive state (useSyncExternalStore)
│   │   ├── index.ts                  #     Store<T>, workspaceStore, projectStore
│   │   └── useStore.ts               #     React hook adapter
│   ├── ux-checklist/                 #   Agentic UI/UX Auditor v5
│   │   ├── index.ts                  #     Orchestrator + CriteriaRegistry + LearningLoop
│   │   ├── agents.ts                 #     5 specialized agents
│   │   ├── github.ts                 #     GitHub Issue/PR bridge
│   │   ├── stream.ts                 #     Real-time streaming + React hook
│   │   ├── memory.ts                 #     Cross-project learning + persistence
│   │   └── ci.ts                     #     CI gate + SARIF + Deploy gate
│   ├── lib/                          #   AI Intelligence Engines
│   │   ├── shannonEngine.ts          #     Multi-agent orchestrator (6 agents)
│   │   ├── evidenceMemory.ts         #     HNSW vector search + sigmoid decay
│   │   ├── goapPlanner.ts            #     Goal-Oriented Action Planning (A*)
│   │   ├── goapShannonBridge.ts      #     GOAP → Shannon → Evidence pipeline
│   │   ├── piiDetection.ts           #     PII scanner (Luhn, SSN, VN IDs)
│   │   ├── usageAnalytics.ts         #     SaaS tiers, quotas, feature flags
│   │   ├── collaborationEngine.ts    #     CRDT (LWW + OR-Set) + PII
│   │   ├── designAnalyzer.ts         #     Design auditor (WCAG 2.2)
│   │   ├── agents/v6/               #     Agent Fleet v6 (22 agents, 8 fleets)
│   │   │   ├── BaseAgent.ts          #       Abstract base + FleetName type
│   │   │   ├── OrchestratorAgent.ts  #       Multi-fleet scheduler + cost gate
│   │   │   ├── WorktreeRunner.ts     #       Git worktree isolation
│   │   │   ├── audit/               #       ArchitectureDriftAgent
│   │   │   ├── command/             #       HumanCommand, IssueToTask
│   │   │   ├── map/                 #       RepoMap, ComponentTrace, DesignContext
│   │   │   ├── self-improve/        #       Diagnostic, Refactor, TestGen, DepAudit, SelfAudit, Benchmark
│   │   │   ├── fix/                 #       CodeFix, DiffApplier, Rollback, useFixApproval
│   │   │   ├── safety/             #       SafetyGate, RegressionGuard, ConflictResolver
│   │   │   ├── verify/             #       TestRunner, LintRunner, BuildVerifier
│   │   │   └── __tests__/          #       25 test files, 192 tests
│   │   └── __tests__/                #     69 test files
│   ├── design/                       #   Template registry + validators
│   │   └── design-md-templates/      #     73 stored DESIGN.md templates
│   └── workspace/                    #   UI components (SplitView, Chat, etc.)
│
├── docs/                             #  Tài liệu kỹ thuật
│   ├── DEV_GUIDE.md                  #     Hướng dẫn phát triển chi tiết
│   └── adr/                          #     Architecture Decision Records
│       ├── 001-dual-mode-auth.md
│       ├── 002-event-driven-architecture.md
│       ├── 003-api-layer-architecture.md
│       └── 004-command-pattern-undo-redo.md
│
├── e2e/                              #  E2E tests (Playwright)
│   └── chat.spec.ts
│
├── .vscode/launch.json               # IDE configurations
├── vercel.json                       # Deployment + security headers
├── vite.web.config.ts                # Web build config
├── vitest.config.ts                  # Test config
└── tsconfig.json                     # TypeScript config

Tính năng

Hệ thống phân loại trạng thái:

• 🟢 Đã triển khai — Production-ready, có test coverage, đã kiểm chứng trên production
• 🟡 Thử nghiệm — Code hoàn chỉnh, có unit tests, chưa kiểm chứng trên production
• 🔴 Kế hoạch — Chưa triển khai, nằm trong roadmap

🟢 Đã triển khai (Production-Ready)

Figma Plugin

• Quét frame/component → chấm điểm AI-readiness (0-100) theo 6 chiều: Structure, Naming, Completeness, Meta, Color, Typography
• Batch scan nhiều selections cùng lúc
• Auto-layout detection + fix suggestions (60% confidence threshold)
• Quick fixes cho các vấn đề phổ biến
• Export compact prompts cho coding agents (Figma-to-code)

Web Workspace

• Chat tab — Groq AI (Llama 3.3 70B), markdown rendering, syntax highlighting
• Code tab — Design.md generation với full tool suite
• SplitView Editor — Soạn markdown, preview, outline, word count, screen completion
• 73 Design.md templates với lazy-loading và category filtering

Design System & Detection

• Design System Profiles — import từ Figma Variables, Styles, Components
• Responsive viewport detection (mobile/tablet/desktop)
• Atomic design classification (atom → page)
• Token mapping (Figma Variables → CSS custom properties)
• EN/VI internationalization

Hạ tầng & Chất lượng

• 1529 tests / 102 files (Vitest) — bao gồm 192 agent fleet v6 tests
• GitHub Actions CI (lint + test + build + E2E)
• Vercel deployment với security headers (CSP, HSTS, X-Frame-Options)
• Local demo auth (localStorage-based)

🟡 Thử nghiệm (Implemented — Chưa Production-Validated)

AI Intelligence Engines

• Shannon Engine v3 — 6 multi-agents, PII-aware execution
• Evidence Memory — HNSW vector search O(log n), sigmoid decay, contradiction detection
• GOAP Planner — A* search, plan caching, dynamic costs, replanning
• PII Detection — Luhn credit card, SSN, Vietnamese CCCD/CMND/phone, email

Agentic UI/UX Auditor (v5)

• 8 agents tự động audit, scoring, fix planning, tạo GitHub Issues
• AI checklist scoring (19 criteria)
• Self-learning loop với Bayesian calibration + user feedback
• Cross-project learning — pattern detection, weight aggregation, knowledge export

Collaboration & Analytics

• Collaboration CRDT (LWW + OR-Set)
• Usage Analytics — 4 SaaS tiers, feature flags, quota enforcement
• CI Gate / Deploy Gate — block deploy nếu audit score < threshold, SARIF v2.1.0

🔴 Kế hoạch (Roadmap)

Cài đặt & Vận hành

Yêu cầu hệ thống

Cài đặt

git clone https://github.com/minhduchd-mds/desygn-ai.git
cd desygn-ai
npm ci

Chạy ứng dụng

# Web workspace (port 5174)
npm run web:dev

# Figma plugin (watch mode)
npm run dev

# Web workspace (port 5173 — alternative)
npm run dev:web

Build production

npm run build       # Figma plugin → dist/
npm run web:build   # Web app → public/

Scripts đầy đủ

API Endpoints

Vercel serverless functions trong api/:

Thư viện Template

73 Design.md templates trong web/src/design-md-templates/.

Danh mục

AI, Developer, Workspace, Product, Commerce, Finance, Automotive, Media

Sử dụng

npx getdesign@latest add <template-id>
# Ví dụ: npx getdesign@latest add airtable

Templates lazy-loaded — chỉ tải metadata lúc khởi động, full content khi chọn.

Kiểm thử & Chất lượng

npm test              # 1529 tests / 102 files
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
npm run lint          # ESLint 9
npm run format:check  # Prettier check
npm run typecheck     # TypeScript (UI + plugin)

Phân bố tests

Build output

Triển khai

Vercel (Production)

{
  "buildCommand": "npm run web:build",
  "outputDirectory": "public",
  "installCommand": "npm ci"
}

Live: design-md-ai-yd6r.vercel.app

Security headers: CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy (cấu hình trong vercel.json).

Figma Plugin

1. npm run build
2. Figma Desktop → Ctrl+Shift+P → Import plugin from manifest
3. Chọn manifest.json trong repo

Cấu hình

Biến môi trường

Tài liệu kỹ thuật

Giấy phép

MIT