Product Design Board Agent

项目简介 / Overview

这是一个用于生成产品设计展示板的 AI 辅助系统，并将结果渲染为可编辑的 Figma 原生节点。

This is an AI-assisted system for generating product design boards and rendering them into editable Figma-native output.

系统接收产品 brief、参考图、草图、渲染图、风格偏好和画板尺寸要求，然后输出结构化内容、确定性的布局决策和 Figma 渲染指令。

The system takes product briefs, reference images, sketches, renders, style preferences, and board size requirements, then produces structured board content, deterministic layout decisions, and Figma render instructions.

核心约束 / Core Constraint

最终设计板必须在 Figma 中保持可编辑。本项目不应只生成一张扁平化图片。文本、图片、frame、callout、shape 和 group 都应尽可能表示为可编辑的 Figma 节点。

The final board must remain editable in Figma. This project should not produce only flattened generated images. Text, images, frames, callouts, shapes, and groups should be represented as editable Figma nodes wherever possible.

架构原则 / Architecture Principles

• 中文：LLM 负责语义规划和内容生成；确定性 layout engine 负责布局、间距、溢出和节点位置。
• English: The LLM handles semantic planning and content generation; the deterministic layout engine handles layout, spacing, overflow, and node placement.
• 中文：语义内容、视觉风格、布局结果和 Figma 渲染指令必须分离。
• English: Semantic content, visual style, layout results, and Figma render instructions must remain separate.
• 中文：优先使用显式 schema 和验证逻辑，而不是只依赖 prompt 中的隐式约定。
• English: Prefer explicit schemas and validation over implicit prompt-only behavior.

技术栈 / Planned Stack

• 前端 / Frontend: Next.js + TypeScript
• 后端 / Backend: FastAPI + Python
• Figma 插件 / Figma plugin: TypeScript
• 共享 schemas / Shared schemas: TypeScript and Python
• 包管理器 / Package manager: pnpm
• Monorepo 结构 / Monorepo layout: apps and packages

仓库结构 / Repository Layout

apps/
  web/               Next.js product/control surface
                     Next.js 产品控制界面
  api/               FastAPI backend and orchestration API
                     FastAPI 后端和编排 API
  figma-plugin/      Figma plugin UI and renderer runtime
                     Figma 插件 UI 和渲染运行时

packages/
  schemas-ts/        TypeScript schema definitions and validators
                     TypeScript schema 定义和验证器
  schemas-py/        Python/Pydantic schema definitions
                     Python/Pydantic schema 定义
  layout-engine/     Deterministic board layout algorithms
                     确定性设计板布局算法
  figma-renderer/    TypeScript helpers for editable Figma node creation
                     用于创建可编辑 Figma 节点的 TypeScript helper
  planner/           LLM planning prompts and structured output handling
                     LLM 规划 prompt 和结构化输出处理
  asset-understanding/ Multimodal asset analysis adapters
                       多模态素材分析适配器

docs/
  Architecture and implementation notes
  架构和实现说明

标准命令 / Standard Commands

这些是仓库逐步实现时应统一使用的根目录命令：

These are the repo-level commands this project should standardize around as implementation fills in:

pnpm lint
pnpm test
pnpm typecheck
pnpm format
pnpm validate

Python 相关的 lint 和 test 应尽量通过根目录脚本调用，或者在 apps/api 中单独记录。

Python-specific linting and tests should either be called by the root scripts or documented in apps/api.

当前后端 API / Current Backend API

当前已实现第一个 FastAPI 端点：

The first FastAPI endpoint is currently implemented:

POST /generate-spec

它接收 brief、画板尺寸、风格偏好和素材列表，并返回经过 Pydantic 验证的语义设计板规格。它暂时不生成布局坐标或 Figma 渲染节点。

It accepts a brief, board size, style preferences, and asset list, then returns a Pydantic-validated semantic board specification. It intentionally does not generate layout geometry or Figma render nodes yet.

开发顺序 / Development Order

1. 定义共享 schema。 / Define shared schemas.
2. 添加 fixtures 和验证。 / Add fixtures and validation.
3. 构建确定性 layout engine。 / Build the deterministic layout engine.
4. 构建 Figma renderer/plugin 垂直切片。 / Build the Figma renderer/plugin vertical slice.
5. 添加结构化 LLM 规划。 / Add structured LLM planning.
6. 添加多模态素材理解。 / Add multimodal asset understanding.
7. 添加局部再生成支持。 / Add partial regeneration support.

相关文档 / Related Docs

• ARCHITECTURE.md: 系统架构 / System architecture
• AGENTS.md: Codex 和 AI agent 协作规则 / Collaboration rules for Codex and AI agents
• docs/MVP.md: MVP 范围和构建计划 / MVP scope and build plan