Agentic UI Development Skill

面向智能体的 UI 组件库开发技能，提供智能化的组件推荐、代码生成和设计系统支持。

Quick Start

pnpm install    # 安装依赖
pnpm start      # 启动文档站点 (http://localhost:8000)
pnpm test       # 运行单元测试
pnpm run build  # 构建项目

Quick Reference – Search Commands

# 搜索组件
python .cursor/skills/agentic-ui-development/scripts/search.py "chat bubble"

# 按域搜索
python .cursor/skills/agentic-ui-development/scripts/search.py "chart" --domain plugin
python .cursor/skills/agentic-ui-development/scripts/search.py "scroll" --domain hook
python .cursor/skills/agentic-ui-development/scripts/search.py "color" --domain token

# 获取推荐方案
python .cursor/skills/agentic-ui-development/scripts/search.py "ai assistant" --recommend

# 生成完整设计系统 (推荐)
# -p 是 --project-name 的简写，用于指定项目名称
python .cursor/skills/agentic-ui-development/scripts/search.py "ai chat" --design-system --project-name "My App"

# 持久化设计系统 (Master + Overrides 模式)
python .cursor/skills/agentic-ui-development/scripts/search.py "ai chat" --design-system --persist --project-name "My App" --page "chat"

Skill Activation

当用户请求以下任务时自动激活：

How It Works

┌─────────────────────────────────────────────────────────────────┐
│  1. USER REQUEST                                                │
│     "创建一个带思维链的 AI 对话气泡"                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  2. DESIGN SYSTEM GENERATION (--design-system)                  │
│     • BM25 search across 4 domains (component, plugin, hook,    │
│       token)                                                    │
│     • Apply reasoning rules from reasoning-rules.json           │
│     • Generate complete recommendation with anti-patterns       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  3. COMPONENT SEARCH (Multi-domain)                             │
│     • Component matching (37 components)                        │
│     • Props API lookup                                          │
│     • Style token recommendations                               │
│     • Related hooks & utilities                                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  4. CODE GENERATION                                             │
│     • Apply component template                                  │
│     • Use design tokens (not hardcoded values)                  │
│     • Include TypeScript types                                  │
│     • Add proper event handlers                                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  5. PRE-DELIVERY CHECKLIST                                      │
│     [ ] Uses Ant Design tokens (no hardcoded colors)            │
│     [ ] TypeScript types complete (no `any`)                    │
│     [ ] Event handlers use `on` prefix                          │
│     [ ] CSS-in-JS with createStyles                             │
│     [ ] Tests included (≥80% coverage)                          │
└─────────────────────────────────────────────────────────────────┘

Design System Generation (NEW)

Generate Complete Recommendation

使用 --design-system 生成完整的组件推荐方案：

python .cursor/skills/agentic-ui-development/scripts/search.py "ai chat assistant" --design-system --project-name "My AI App"

输出包含：

• 推荐组件列表
• 推荐 Hooks
• 推荐插件
• 关键设计令牌
• 样式优先级
• 反模式警告
• 交付前检查清单

Persist with Master + Overrides Pattern

持久化设计系统到文件，支持分层覆盖：

# 创建 MASTER.md
python .cursor/skills/agentic-ui-development/scripts/search.py "ai chat" --design-system --persist --project-name "My App"

# 同时创建页面覆盖文件
python .cursor/skills/agentic-ui-development/scripts/search.py "ai chat" --design-system --persist --project-name "My App" --page "chat"

生成文件结构：

design-system/my-app/
├── MASTER.md       # 全局设计规则 (Source of Truth)
└── pages/
    └── chat.md     # 页面特定覆盖规则

分层检索逻辑：

1. 构建页面时，先检查 design-system/<project>/pages/[page].md
2. 如果页面文件存在，其规则覆盖 Master 文件
3. 如果不存在，严格使用 design-system/<project>/MASTER.md

Component Categories

🤖 AI Core Components

✍️ Editor Components

📐 Layout Components

🎨 Utility Components

🔘 Button Components

🔌 Plugin System

Design System Rules

✅ DO (Best Practices)

// 1. Use Ant Design tokens
const useStyles = createStyles(({ token }) => ({
  container: {
    padding: token.padding,           // ✅ Not '16px'
    color: token.colorText,           // ✅ Not '#000'
    borderRadius: token.borderRadius, // ✅ Not '6px'
  },
}));

// 2. Complete TypeScript types
interface MyComponentProps {
  onSelect?: (item: Item) => void;  // ✅ on prefix
  config?: MyConfig;                 // ✅ Config suffix
}

// 3. CSS-in-JS pattern
import { createStyles } from '@ant-design/cssinjs';

❌ DON’T (Anti-Patterns)

// 1. Hardcoded values
padding: '16px',           // ❌ Use token.padding
color: '#1890ff',          // ❌ Use token.colorPrimary
backgroundColor: 'white',  // ❌ Use token.colorBgContainer

// 2. Any types
props: any                 // ❌ Define proper interface

// 3. Inline styles
style={{ padding: 16 }}    // ❌ Use createStyles

// 4. Wrong event naming
handleClick               // ❌ Use onClick

File Structure Pattern

ComponentName/
├── components/     # 子组件
├── hooks/          # 自定义 Hook (useXxx.ts)
├── types/          # 类型定义
├── __tests__/      # 测试文件 (ComponentName.test.tsx)
├── index.tsx       # 主组件入口
└── style.ts        # CSS-in-JS 样式

Pre-Delivery Checklist

Before completing any component task:

[ ] Uses @ant-design/cssinjs createStyles
[ ] All colors from token system
[ ] TypeScript types complete (no `any`)
[ ] Event handlers with `on` prefix
[ ] BEM class naming (.component__element--modifier)
[ ] Unit tests included
[ ] Proper error boundaries
[ ] Accessibility (aria-* attributes)
[ ] Performance (React.memo, useMemo, useCallback)

Search Command Reference

Available Domains

Command Options

# 基本搜索
python .cursor/skills/agentic-ui-development/scripts/search.py "query"

# 指定域搜索
python .cursor/skills/agentic-ui-development/scripts/search.py "query" --domain component

# 获取推荐方案
python .cursor/skills/agentic-ui-development/scripts/search.py "query" --recommend

# 生成设计系统 (--project-name 可简写为 -p)
python .cursor/skills/agentic-ui-development/scripts/search.py "query" --design-system --project-name "Project"

# 持久化设计系统
python .cursor/skills/agentic-ui-development/scripts/search.py "query" --design-system --persist --project-name "Project" --page "page"

# 输出格式 (--format 可简写为 -f)
python .cursor/skills/agentic-ui-development/scripts/search.py "query" --format json      # JSON
python .cursor/skills/agentic-ui-development/scripts/search.py "query" --format markdown  # Markdown
python .cursor/skills/agentic-ui-development/scripts/search.py "query" --format ascii     # ASCII (default)

# 限制结果数量 (--limit 可简写为 -n)
python .cursor/skills/agentic-ui-development/scripts/search.py "query" --limit 3

Example: Design System Output

+------------------------------------------------------------------------------------------+
|  TARGET: MY AI APP - AGENTIC UI RECOMMENDATION
+------------------------------------------------------------------------------------------+
|
|  QUERY: ai chat assistant
|  RULE MATCHED: ai-assistant
|
|  RECOMMENDED COMPONENTS:
|     Bubble.AIBubble, ThoughtChainList, ToolUseBar, WelcomeMessage
|
|  RECOMMENDED HOOKS:
|     useAutoScroll, useSpeechSynthesis
|
|  RECOMMENDED PLUGINS:
|     N/A
|
|  KEY TOKENS:
|     colorPrimary, colorSuccess, motionDurationMid
|
|  STYLE PRIORITY:
|     modern, glassmorphism, dark-mode
|
|  ANTI-PATTERNS (AVOID):
|     ❌ No thought chain for AI
|     ❌ Missing streaming support
|     ❌ No tool call visibility
|
|  PRE-DELIVERY CHECKLIST:
|     [ ] Uses @ant-design/cssinjs createStyles
|     [ ] All colors from token system
|     [ ] TypeScript types complete (no any)
|     [ ] Event handlers with 'on' prefix
|     [ ] BEM class naming
|     [ ] Unit tests included (≥80% coverage)
|     [ ] Proper error boundaries
|
+------------------------------------------------------------------------------------------+

Data Files

Design Tokens (Quick Reference)

使用 Ant Design Token 系统，禁止硬编码值。

Color Tokens

Spacing Tokens

Usage

const useStyles = createStyles(({ token }) => ({
  container: {
    padding: token.padding,        // DO: token
    color: token.colorText,        // DO: token
    // padding: '16px',            // DON'T: hardcode
  },
}));

Plugins (Quick Reference)

<MarkdownEditor plugins={['code', 'katex', 'mermaid', 'chart']} />

Component API Examples

Bubble

import { Bubble } from '@ant-design/agentic-ui';

<Bubble.AIBubble
  content="分析完成"
  thoughtChain={[
    { type: 'thought', content: '分析需求' },
    { type: 'action', content: '执行查询' },
  ]}
  status="success"
  streaming={true}
/>

<Bubble.UserBubble content="请分析数据" avatar={{ src: '/avatar.png' }} />

ThoughtChainList

import { ThoughtChainList } from '@ant-design/agentic-ui';

<ThoughtChainList
  items={[
    { type: 'thought', title: '分析', status: 'completed' },
    { type: 'action', title: '执行', status: 'loading', costMillis: 234 },
  ]}
  collapsed={false}
  onToggle={(collapsed) => {}}
/>

ToolUseBar

import { ToolUseBar } from '@ant-design/agentic-ui';

<ToolUseBar
  name="搜索工具"
  status="success"
  params={{ query: 'React' }}
  result={{ items: [...], count: 10 }}
  costMillis={1234}
/>

MarkdownEditor

import { MarkdownEditor } from '@ant-design/agentic-ui';

<MarkdownEditor
  value={markdown}
  onChange={setMarkdown}
  plugins={['code', 'katex', 'mermaid']}
  toolbar={{ bold: true, italic: true, code: true }}
/>

Workspace

import Workspace from '@ant-design/agentic-ui';

<Workspace
  activeKey="file"
  tabs={[
    { key: 'browser', title: '浏览器', content: <BrowserPreview /> },
    { key: 'file', title: '文件', content: <FileViewer /> },
  ]}
  onTabChange={(key) => {}}
/>

Code Templates

Component Template

import React from 'react';
import { createStyles } from '@ant-design/cssinjs';

export interface {{ComponentName}}Props {
  className?: string;
  children?: React.ReactNode;
  onSelect?: (value: string) => void;
}

const useStyles = createStyles(({ token }) => ({
  container: {
    padding: token.padding,
    backgroundColor: token.colorBgContainer,
    borderRadius: token.borderRadius,
  },
}));

export const {{ComponentName}}: React.FC<{{ComponentName}}Props> = ({
  className, children, onSelect,
}) => {
  const { styles, cx } = useStyles();
  return <div className={cx(styles.container, className)}>{children}</div>;
};

Hook Template

import { useState, useCallback } from 'react';

export const use{{HookName}} = (defaultValue = '') => {
  const [value, setValue] = useState(defaultValue);
  const reset = useCallback(() => setValue(defaultValue), [defaultValue]);
  return { value, setValue, reset };
};

Test Template

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { describe, it, expect, vi } from 'vitest';

describe('{{ComponentName}}', () => {
  it('should render', () => {
    render(<{{ComponentName}} />);
    expect(screen.getByRole('button')).toBeInTheDocument();
  });

  it('should handle click', async () => {
    const onClick = vi.fn();
    render(<{{ComponentName}} onClick={onClick} />);
    await userEvent.click(screen.getByRole('button'));
    expect(onClick).toHaveBeenCalledTimes(1);
  });
});

Test Commands

pnpm test             # 单元测试
pnpm test:coverage    # 带覆盖率 (>=80%)
pnpm test:e2e         # E2E 测试

Commit Convention

<type>(<scope>): <description>

Types: feat | fix | docs | style | refactor | perf | test | chore
Scopes: bubble | editor | workspace | history | plugin | core

Examples:

• feat(bubble): add streaming text animation
• fix(editor): resolve cursor position issue
• test(thought-chain): add unit tests for ToolCall