designer-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Designer Skills for LlamaFarm

LlamaFarm的Designer技能指南

Framework-specific patterns and checklists for the Designer subsystem (React 18 + TanStack Query + TailwindCSS + Radix UI).

Designer子系统的框架特定模式与检查清单（React 18 + TanStack Query + TailwindCSS + Radix UI）。

Overview

概述

The Designer is a browser-based project workbench for building AI applications. It provides config editing, chat testing, dataset management, RAG configuration, and model selection.

Designer是一个基于浏览器的项目工作台，用于构建AI应用。它提供配置编辑、聊天测试、数据集管理、RAG配置和模型选择功能。

Tech Stack

技术栈

Technology	Version	Purpose
React	18.2	UI framework with StrictMode
TypeScript	5.2+	Type safety
TanStack Query	v5	Server state management
TailwindCSS	3.3	Utility-first CSS
Radix UI	1.x	Accessible component primitives
Vite	6.x	Build tooling and dev server
React Router	v7	Client-side routing
Vitest	1.x	Testing framework
axios	1.x	HTTP client
framer-motion	12.x	Animations

技术	版本	用途
React	18.2	开启StrictMode的UI框架
TypeScript	5.2+	类型安全
TanStack Query	v5	服务端状态管理
TailwindCSS	3.3	实用优先的CSS框架
Radix UI	1.x	可访问的组件原语
Vite	6.x	构建工具与开发服务器
React Router	v7	客户端路由
Vitest	1.x	测试框架
axios	1.x	HTTP客户端
framer-motion	12.x	动画库

Directory Structure

目录结构

designer/src/
  api/          # API service modules (axios-based)
  assets/       # Static assets and icons
  components/   # Feature-organized React components
    ui/         # Radix-based primitive components
  contexts/     # React Context providers
  hooks/        # Custom hooks (TanStack Query wrappers)
  lib/          # Utilities (cn, etc.)
  types/        # TypeScript type definitions
  utils/        # Helper functions
  test/         # Test utilities, factories, mocks

designer/src/
  api/          # 基于axios的API服务模块
  assets/       # 静态资源与图标
  components/   # 按功能划分的React组件
    ui/         # 基于Radix的原语组件
  contexts/     # React Context提供者
  hooks/        # 自定义钩子（TanStack Query封装）
  lib/          # 工具函数（如cn等）
  types/        # TypeScript类型定义
  utils/        # 辅助函数
  test/         # 测试工具、工厂函数、模拟数据

Prerequisites: Shared Skills

前置要求：通用技能

Before applying Designer-specific patterns, ensure compliance with:

TypeScript Skills - Strict typing, patterns, security
React Skills - Component patterns, hooks, state management

在应用Designer特定模式之前，请确保遵循以下规范：

TypeScript 技能 - 严格类型、模式、安全性
React 技能 - 组件模式、钩子、状态管理

Framework-Specific Guides

框架特定指南

Guide	Description
tanstack-query.md	Query/Mutation patterns, caching, invalidation
tailwind.md	TailwindCSS patterns, theming, responsive design
radix.md	Radix UI component patterns, accessibility
performance.md	Frontend optimizations, bundle size, lazy loading

指南	描述
tanstack-query.md	查询/变更模式、缓存、失效策略
tailwind.md	TailwindCSS模式、主题配置、响应式设计
radix.md	Radix UI组件模式、可访问性
performance.md	前端优化、包体积、懒加载

Key Patterns

核心模式

API Client Configuration

API客户端配置

typescript

// Centralized client with interceptors
export const apiClient = axios.create({
  baseURL: API_BASE_URL,
  headers: { 'Content-Type': 'application/json' },
  timeout: 60000,
})

// Error handling interceptor
apiClient.interceptors.response.use(
  response => response,
  (error: AxiosError) => {
    if (error.response?.status === 422) {
      throw new ValidationError('Validation error', error.response.data)
    }
    throw new NetworkError('Request failed', error)
  }
)

typescript

// 带拦截器的集中式客户端
export const apiClient = axios.create({
  baseURL: API_BASE_URL,
  headers: { 'Content-Type': 'application/json' },
  timeout: 60000,
})

// 错误处理拦截器
apiClient.interceptors.response.use(
  response => response,
  (error: AxiosError) => {
    if (error.response?.status === 422) {
      throw new ValidationError('Validation error', error.response.data)
    }
    throw new NetworkError('Request failed', error)
  }
)

Query Client Configuration

查询客户端配置

typescript

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60_000,
      gcTime: 5 * 60_000,
      retry: 2,
      retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30_000),
      refetchOnWindowFocus: false,
    },
    mutations: { retry: 1 },
  },
})

typescript

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60_000,
      gcTime: 5 * 60_000,
      retry: 2,
      retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30_000),
      refetchOnWindowFocus: false,
    },
    mutations: { retry: 1 },
  },
})

Class Merging Utility

类名合并工具

typescript

// lib/utils.ts - Always use cn() for Tailwind classes
import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

typescript

// lib/utils.ts - 始终使用cn()处理Tailwind类名
import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

Theme Provider Pattern

主题提供者模式

typescript

const ThemeContext = createContext<ThemeContextType | undefined>(undefined)

export function useTheme() {
  const context = useContext(ThemeContext)
  if (!context) throw new Error('useTheme must be used within ThemeProvider')
  return context
}

// Apply via Tailwind dark mode class strategy
useEffect(() => {
  document.documentElement.classList.toggle('dark', theme === 'dark')
}, [theme])

typescript

const ThemeContext = createContext<ThemeContextType | undefined>(undefined)

export function useTheme() {
  const context = useContext(ThemeContext)
  if (!context) throw new Error('useTheme must be used within ThemeProvider')
  return context
}

// 通过Tailwind暗色模式类策略应用主题
useEffect(() => {
  document.documentElement.classList.toggle('dark', theme === 'dark')
}, [theme])

Component Conventions

组件规范

Feature Components

功能组件

Located in
```
components/{Feature}/
```
directories
One component per file, named after the component
Co-located with feature-specific types and utilities

位于
```
components/{Feature}/
```
目录下
每个文件对应一个组件，文件名与组件名一致
与功能特定的类型和工具函数放在同一目录

UI Primitives

UI原语

Located in
```
components/ui/
```
Wrap Radix UI primitives with Tailwind styling
Use
```
forwardRef
```
for ref forwarding
Set
```
displayName
```
for DevTools

位于
```
components/ui/
```
目录下
用Tailwind样式封装Radix UI原语
使用
```
forwardRef
```
转发引用
设置
```
displayName
```
以便在DevTools中识别

Icons

图标

Located in
```
assets/icons/
```
Functional components accepting SVG props
Use
```
lucide-react
```
for standard icons

位于
```
assets/icons/
```
目录下
接受SVG属性的函数式组件
标准图标使用
```
lucide-react
```
库

Testing

测试

typescript

// Use MSW for API mocking
import { server } from '@/test/mocks/server'
import { renderWithProviders } from '@/test/utils'

beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

test('renders with query data', async () => {
  renderWithProviders(<MyComponent />)
  await screen.findByText('Expected text')
})

typescript

// 使用MSW模拟API
import { server } from '@/test/mocks/server'
import { renderWithProviders } from '@/test/utils'

beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

test('renders with query data', async () => {
  renderWithProviders(<MyComponent />)
  await screen.findByText('Expected text')
})

Checklist Summary

检查清单摘要

Category	Critical	High	Medium	Low
TanStack Query	3	4	3	2
TailwindCSS	2	3	4	2
Radix UI	3	3	2	1
Performance	2	4	3	2

分类	关键	高优先级	中优先级	低优先级
TanStack Query	3	4	3	2
TailwindCSS	2	3	4	2
Radix UI	3	3	2	1
性能	2	4	3	2