@zhama/a2ui

A2UI Protocol - React Implementation for AI-Driven Dynamic User Interfaces

A2UI 协议 - 用于 AI 驱动动态用户界面的 React 实现

English | 中文

English

📖 Overview

A2UI (Agent-to-User Interface) is a protocol that enables AI agents to dynamically generate and control user interfaces. This library provides a complete React implementation based on Google's A2UI protocol specification, allowing AI agents to create rich, interactive UIs through structured data instead of plain text responses.

🎬 Live Demo

See A2UI in action! The demo showcases an AI training assistant that generates dynamic, interactive UIs based on user conversations.

Try it yourself:

cd examples/basic-demo
npm install
npm run dev

Then open http://localhost:5174 and try these commands:

• Type hello - Get a welcome screen with topic cards
• Click a topic button - See a structured learning path
• Type practice - Get interactive quiz questions
• Type progress - View learning statistics

What you'll see:

💡 Note: All UIs above are generated dynamically by the AI agent using A2UI protocol - no hardcoded components!

✨ Features

• 🤖 AI-First Design - Built specifically for AI-driven UI generation
• 📦 Complete Protocol Support - Full implementation of A2UI protocol specifications
• 🎨 Standalone Style System - No Tailwind dependency, built-in CSS utility classes with a2- prefix
• 🔒 Style Isolation - Avoid conflicts with host applications
• 🌓 Auto Dark Mode - Uses CSS light-dark() function
• 🧩 Rich Components - Comprehensive set of UI components (Text, Button, Card, List, TextField, etc.)
• 🔌 Extensible - Support for custom component registration
• 📱 Responsive - Mobile-first responsive design
• ⚡ Performance - Optimized rendering with React best practices
• 🎯 Type-Safe - Full TypeScript support with comprehensive type definitions
• 🌐 Framework Agnostic - Core protocol can be adapted to other frameworks
• 🎭 Event Handling - Built-in action handling system for interactive components

🚀 Quick Start

Installation

npm install @zhama/a2ui
# or
yarn add @zhama/a2ui
# or
pnpm add @zhama/a2ui

Peer Dependencies

npm install react react-dom react-markdown

Basic Setup

1. Wrap with StyleProvider and ThemeProvider

import { StyleProvider, ThemeProvider, A2UIRoot } from '@zhama/a2ui';

function App() {
  return (
    <StyleProvider>
      <ThemeProvider>
        <div className="a2ui-root">
          {/* Your A2UI components */}
        </div>
      </ThemeProvider>
    </StyleProvider>
  );
}

💡 Note: StyleProvider automatically injects A2UI's CSS utility classes. The a2ui-root class applies base styles and CSS variables.

2. Use A2UIRoot Component

import { A2UIRoot } from '@zhama/a2ui';
import type { AnyComponentNode } from '@zhama/a2ui/types';

function App() {
  const components: AnyComponentNode[] = [
    {
      id: 'text-1',
      type: 'Text',
      properties: {
        text: { literal: 'Hello from A2UI!' },
        usageHint: { literal: 'h1' },
      },
    },
    {
      id: 'button-1',
      type: 'Button',
      properties: {
        child: {
          id: 'btn-text',
          type: 'Text',
          properties: {
            text: { literal: 'Click Me' },
          },
        },
        action: {
          type: 'postback',
          payload: 'button_clicked',
        },
      },
    },
  ];

  const handleAction = (event) => {
    console.log('Action triggered:', event);
  };

  return (
    <A2UIRoot
      childComponents={components}
      processor={null}
      surfaceId={null}
      onAction={handleAction}
    />
  );
}

📦 Package Exports

The library provides multiple entry points for different use cases:

// Main entry - everything
import { A2UIRoot, createButton, createText } from '@zhama/a2ui';

// Type definitions only
import type { AnyComponentNode, ButtonNode } from '@zhama/a2ui/types';

// Data utilities
import { A2UIRegistry } from '@zhama/a2ui/data';

// Event types
import type { A2UIAction } from '@zhama/a2ui/events';

// Styles
import '@zhama/a2ui/styles';

// UI components individually
import { Button, Card, List } from '@zhama/a2ui/ui';

// Context providers
import { A2UIProvider, useA2UI } from '@zhama/a2ui/context';

🎨 Theming

A2UI comes with a customizable theme system:

import { ThemeProvider, createTheme } from '@zhama/a2ui';

const customTheme = createTheme({
  components: {
    Button: {
      'a2-bgc-p40': true,  // Custom button background
      'a2-br-4': true,     // Larger border radius
    },
    Card: {
      'a2-shadow-lg': true, // Larger shadow
    },
  },
});

function App() {
  return (
    <ThemeProvider theme={customTheme}>
      <YourApp />
    </ThemeProvider>
  );
}

🎨 Style System

A2UI uses a standalone CSS utility class system that doesn't depend on Tailwind CSS.

Class Naming Convention

All style classes use the a2- prefix:

| Category | Prefix | Examples | |----------|--------|----------| | Layout | a2-p-*, a2-m-*, a2-gap-* | a2-p-4, a2-mx-2, a2-gap-2 | | Display | a2-dsp-* | a2-dsp-flex, a2-dsp-grid | | Flex | a2-flex-*, a2-al-*, a2-jc-* | a2-flex-1, a2-al-center | | Colors | a2-c-*, a2-bgc-*, a2-bc-* | a2-c-p50, a2-bgc-n0 | | Typography | a2-font-*, a2-fw-*, a2-text-* | a2-font-sans, a2-fw-500 | | Border | a2-br-*, a2-bw-*, a2-bs-* | a2-br-4, a2-bw-1 | | Behavior | a2-opacity-*, a2-shadow-* | a2-opacity-80, a2-shadow-md |

Color System

Uses OKLCH color space with 6 palettes:

| Prefix | Description | |--------|-------------| | p | Primary - Main color | | s | Secondary - Secondary color | | t | Tertiary - Third color | | n | Neutral - Gray tones | | nv | Neutral Variant - Neutral variant | | e | Error - Error color |

Color scale: 0 (lightest) ~ 100 (darkest)

/* Examples */
.a2-c-p50 { /* Primary 50% */ }
.a2-bgc-n0 { /* White background */ }
.a2-bc-e40 { /* Error color border */ }

Manual Style Injection

For SSR or special scenarios:

import { getStylesCSS } from '@zhama/a2ui';

// Get complete CSS string
const css = getStylesCSS();

// Inject into head
const style = document.createElement('style');
style.textContent = css;
document.head.appendChild(style);

🧩 Available Components

| Component | Description | Use Case | |-----------|-------------|----------| | Text | Render formatted text with markdown support | Headings, paragraphs, captions | | Button | Interactive button with action support | User actions, navigation | | Card | Container for grouped content | Content grouping, layouts | | List | Vertical or horizontal list layout | Multiple items display | | Row | Horizontal layout container | Side-by-side elements | | Column | Vertical layout container | Stacked elements | | TextField | Text input field | User input, forms | | CheckBox | Checkbox input | Boolean selections | | Image | Display images | Visual content | | Tabs | Tabbed interface | Multiple views | | Surface | Container with elevation | Modal dialogs, panels |

💼 Use Cases

A2UI is perfect for scenarios where AI agents need to provide rich, interactive experiences:

🎓 AI Training & Education

• Dynamic course content generation
• Interactive quizzes and assessments
• Personalized learning paths
• Progress tracking dashboards

🤖 Conversational AI Assistants

• Customer support with form filling
• Product recommendations with cards
• Multi-step workflows
• Data visualization

📊 Business Applications

• Report generation with charts
• Data entry forms
• Approval workflows
• Dashboard creation

🛠️ Development Tools

• Code generation with syntax highlighting
• Interactive documentation
• Configuration wizards
• Debugging interfaces

🏗️ Architecture

A2UI follows a two-layer architecture inspired by modern AI applications:

1. ContentModel Layer (High-level Semantic)

   • Scene-based content structure (Welcome, Learning, Practice, etc.)
   • Business logic representation
   • LLM-friendly format - AI outputs meaningful scenes, not UI components
   • Easy to understand and modify

2. A2UI Protocol Layer (Low-level UI)

   • ComponentNode structure (Button, Card, List, etc.)
   • UI rendering specification
   • Framework implementation
   • Optimized for rendering

Flow:

┌─────────────┐     ┌──────────────┐     ┌─────────────┐     ┌──────────┐
│ LLM Output  │ →   │ ContentModel │  →  │   Scene     │  →  │ A2UI UI  │
│  (JSON)     │     │  (Semantic)  │     │  Renderer   │     │ (React)  │
└─────────────┘     └──────────────┘     └─────────────┘     └──────────┘
                         ↓                       ↓
                    Scene: "welcome"      ComponentNodes
                    Topics: [...]          [Card, Button, ...]

Benefits:

• ✅ Separation of Concerns: LLM focuses on content, not UI details
• ✅ Flexibility: Change UI rendering without changing LLM prompts
• ✅ Testability: Test content logic separately from UI
• ✅ Maintainability: Easier to update and extend

📚 Examples

Check out the /examples directory for complete examples:

• basic-demo: Full-featured demo showcasing all A2UI capabilities
• Includes 7 different scenes (Welcome, Learning, Practice, Feedback, Progress, Conversation)
• Interactive components with action handling
• ContentModel to ComponentNode rendering pipeline

To run the examples:

cd examples/basic-demo
npm install
npm run dev

🛠️ Development

Setup

# Install dependencies
pnpm install

# Build the library
pnpm run build

# Run type checking
pnpm run type-check

# Lint
pnpm run lint

# Format code
pnpm run format

Project Structure

zhama/a2ui/
├── src/
│   ├── types/          # TypeScript type definitions
│   ├── data/           # Data structures and utilities
│   ├── events/         # Event handling
│   ├── ui/             # React components
│   ├── context/        # React context providers
│   ├── styles/         # CSS and theme definitions
│   └── index.ts        # Main entry point
├── examples/           # Example applications
│   └── basic-demo/     # Full-featured demo
├── dist/               # Build output
└── README.md

🤝 Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Write clear, self-documenting code
• Follow the existing code style (enforced by ESLint/Prettier)
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by Google's A2UI Protocol
• Built with React and TypeScript

📞 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]
• 🌐 Website: https://zhama.com

❓ FAQ

A2UI components are designed to be generated dynamically by AI agents, not manually coded. They use a protocol-based approach where AI outputs structured data (ContentModel) that gets rendered as UI, rather than AI generating component code.

Yes! While designed for AI-driven UIs, you can manually create ComponentNode structures and render them with A2UIRoot. It's just more tedious than traditional React development.

A2UI is protocol-first, designed for AI generation. shadcn/ui is developer-first, designed for manual coding. You can use both together - A2UI for AI-generated content, shadcn for developer-built features.

Any LLM that can output structured JSON works. We've tested with:

• GPT-4, GPT-3.5-turbo (OpenAI)
• Claude 3 (Anthropic)
• Gemini Pro (Google)
• Open-source models via local inference

Yes! A2UI uses a standalone CSS utility class system with the a2- prefix. You can override default styles through the ThemeProvider theme prop or by overriding CSS variables.

Yes! A2UI is stable and being used in production applications. However, as with any v1.0 library, expect minor API refinements in future versions.

中文

📖 概述

A2UI（Agent-to-User Interface，智能体到用户界面）是一种协议，使 AI 智能体能够动态生成和控制用户界面。本库基于 Google 的 A2UI 协议规范提供了完整的 React 实现，允许 AI 智能体通过结构化数据而非纯文本响应来创建丰富的交互式 UI。

🎬 在线演示

查看 A2UI 的实际效果！演示展示了一个 AI 培训助手，它根据用户对话动态生成交互式 UI。

亲自试用：

cd examples/basic-demo
npm install
npm run dev

然后打开 http://localhost:5174 并尝试以下命令：

• 输入 hello - 获取带主题卡片的欢迎屏幕
• 点击主题按钮 - 查看结构化学习路径
• 输入 practice - 获取交互式练习题
• 输入 progress - 查看学习统计

你将看到：

💡 注意： 上面所有 UI 都是由 AI 智能体使用 A2UI 协议动态生成的 - 没有硬编码组件！

✨ 特性

• 🤖 AI 优先设计 - 专为 AI 驱动的 UI 生成而构建
• 📦 完整协议支持 - 完整实现 A2UI 协议规范
• 🎨 独立样式系统 - 不依赖 Tailwind，自带完整的 a2- 前缀 CSS 工具类
• 🔒 样式隔离 - 使用 a2- 前缀避免与宿主应用冲突
• 🌓 自动暗色模式 - 使用 CSS light-dark() 函数
• 🧩 丰富组件 - 全面的 UI 组件集（Text、Button、Card、List、TextField 等）
• 🔌 可扩展 - 支持自定义组件注册
• 📱 响应式 - 移动优先的响应式设计
• ⚡ 高性能 - 遵循 React 最佳实践的优化渲染
• 🎯 类型安全 - 完整的 TypeScript 支持和全面的类型定义
• 🌐 框架无关 - 核心协议可适配其他框架
• 🎭 事件处理 - 内置交互组件的动作处理系统

🚀 快速开始

安装

npm install @zhama/a2ui
# 或
yarn add @zhama/a2ui
# 或
pnpm add @zhama/a2ui

对等依赖

npm install react react-dom react-markdown

基础设置

1. 使用 StyleProvider 和 ThemeProvider 包裹应用

import { StyleProvider, ThemeProvider, A2UIRoot } from '@zhama/a2ui';

function App() {
  return (
    <StyleProvider>
      <ThemeProvider>
        <div className="a2ui-root">
          {/* 你的 A2UI 组件 */}
        </div>
      </ThemeProvider>
    </StyleProvider>
  );
}

💡 注意： StyleProvider 会自动注入 A2UI 的 CSS 工具类。a2ui-root 类会应用基础样式和 CSS 变量。

2. 使用 A2UIRoot 组件

import { A2UIRoot } from '@zhama/a2ui';
import type { AnyComponentNode } from '@zhama/a2ui/types';

function App() {
  const components: AnyComponentNode[] = [
    {
      id: 'text-1',
      type: 'Text',
      properties: {
        text: { literal: 'Hello from A2UI!' },
        usageHint: { literal: 'h1' },
      },
    },
    {
      id: 'button-1',
      type: 'Button',
      properties: {
        child: {
          id: 'btn-text',
          type: 'Text',
          properties: {
            text: { literal: '点击我' },
          },
        },
        action: {
          type: 'postback',
          payload: 'button_clicked',
        },
      },
    },
  ];

  const handleAction = (event) => {
    console.log('动作触发:', event);
  };

  return (
    <A2UIRoot
      childComponents={components}
      processor={null}
      surfaceId={null}
      onAction={handleAction}
    />
  );
}

📦 包导出

库提供多个入口点用于不同用例：

// 主入口 - 所有内容
import { A2UIRoot, createButton, createText } from '@zhama/a2ui';

// 仅类型定义
import type { AnyComponentNode, ButtonNode } from '@zhama/a2ui/types';

// 数据工具
import { A2UIRegistry } from '@zhama/a2ui/data';

// 事件类型
import type { A2UIAction } from '@zhama/a2ui/events';

// 样式
import '@zhama/a2ui/styles';

// 单独的 UI 组件
import { Button, Card, List } from '@zhama/a2ui/ui';

// Context 提供者
import { A2UIProvider, useA2UI } from '@zhama/a2ui/context';

🎨 主题化

A2UI 自带可定制的主题系统：

import { ThemeProvider, createTheme } from '@zhama/a2ui';

const customTheme = createTheme({
  components: {
    Button: {
      'a2-bgc-p40': true,  // 自定义按钮背景
      'a2-br-4': true,     // 更大圆角
    },
    Card: {
      'a2-shadow-lg': true, // 更大阴影
    },
  },
});

function App() {
  return (
    <ThemeProvider theme={customTheme}>
      <YourApp />
    </ThemeProvider>
  );
}

🎨 样式系统

A2UI 使用独立的 CSS 工具类系统，不依赖 Tailwind CSS。

类名规范

所有样式类使用 a2- 前缀：

| 类别 | 前缀 | 示例 | |------|------|------| | Layout | a2-p-*, a2-m-*, a2-gap-* | a2-p-4, a2-mx-2, a2-gap-2 | | Display | a2-dsp-* | a2-dsp-flex, a2-dsp-grid | | Flex | a2-flex-*, a2-al-*, a2-jc-* | a2-flex-1, a2-al-center | | Colors | a2-c-*, a2-bgc-*, a2-bc-* | a2-c-p50, a2-bgc-n0 | | Typography | a2-font-*, a2-fw-*, a2-text-* | a2-font-sans, a2-fw-500 | | Border | a2-br-*, a2-bw-*, a2-bs-* | a2-br-4, a2-bw-1 | | Behavior | a2-opacity-*, a2-shadow-* | a2-opacity-80, a2-shadow-md |

颜色系统

使用 OKLCH 色彩空间，支持 6 个调色板：

| 前缀 | 说明 | |------|------| | p | Primary - 主色调 | | s | Secondary - 次要色 | | t | Tertiary - 第三色 | | n | Neutral - 中性灰色 | | nv | Neutral Variant - 中性变体 | | e | Error - 错误色 |

色阶：0 (最亮) ~ 100 (最暗)

/* 示例 */
.a2-c-p50 { /* 主色 50% */ }
.a2-bgc-n0 { /* 白色背景 */ }
.a2-bc-e40 { /* 错误色边框 */ }

手动注入样式

对于 SSR 或特殊场景：

import { getStylesCSS } from '@zhama/a2ui';

// 获取完整 CSS 字符串
const css = getStylesCSS();

// 注入到 head
const style = document.createElement('style');
style.textContent = css;
document.head.appendChild(style);

🧩 可用组件

| 组件 | 描述 | 使用场景 | |------|------|---------| | Text | 支持 markdown 的格式化文本渲染 | 标题、段落、说明文字 | | Button | 支持动作的交互按钮 | 用户操作、导航 | | Card | 分组内容的容器 | 内容分组、布局 | | List | 垂直或水平列表布局 | 多项目展示 | | Row | 水平布局容器 | 并排元素 | | Column | 垂直布局容器 | 堆叠元素 | | TextField | 文本输入框 | 用户输入、表单 | | CheckBox | 复选框输入 | 布尔选择 | | Image | 图片显示 | 视觉内容 | | Tabs | 选项卡界面 | 多视图 | | Surface | 带高度的容器 | 模态对话框、面板 |

💼 使用场景

A2UI 非常适合 AI 智能体需要提供丰富交互体验的场景：

🎓 AI 培训与教育

• 动态课程内容生成
• 交互式测验和评估
• 个性化学习路径
• 进度追踪仪表板

🤖 对话式 AI 助手

• 带表单填写的客户支持
• 带卡片的产品推荐
• 多步骤工作流程
• 数据可视化

📊 商业应用

• 带图表的报告生成
• 数据录入表单
• 审批工作流程
• 仪表板创建

🛠️ 开发工具

• 带语法高亮的代码生成
• 交互式文档
• 配置向导
• 调试界面

🏗️ 架构

A2UI 采用受现代 AI 应用启发的两层架构：

1. ContentModel 层（高级语义）

   • 基于场景的内容结构（欢迎、学习、练习等）
   • 业务逻辑表示
   • LLM 友好格式 - AI 输出有意义的场景，而非 UI 组件
   • 易于理解和修改

2. A2UI 协议层（低级 UI）

   • ComponentNode 结构（Button、Card、List 等）
   • UI 渲染规范
   • 框架实现
   • 为渲染优化

流程：

┌─────────────┐     ┌──────────────┐     ┌─────────────┐     ┌──────────┐
│ LLM 输出    │ →   │ ContentModel │  →  │   场景      │  →  │ A2UI UI  │
│  (JSON)     │     │  (语义)      │     │  渲染器     │     │ (React)  │
└─────────────┘     └──────────────┘     └─────────────┘     └──────────┘
                         ↓                       ↓
                    场景: "welcome"        ComponentNodes
                    主题: [...]            [Card, Button, ...]

优势：

• ✅ 关注点分离: LLM 专注于内容，而非 UI 细节
• ✅ 灵活性: 更改 UI 渲染而无需更改 LLM 提示词
• ✅ 可测试性: 独立测试内容逻辑和 UI
• ✅ 可维护性: 更容易更新和扩展

📚 示例

查看 /examples 目录获取完整示例：

• basic-demo: 展示所有 A2UI 功能的完整演示
• 包含 7 个不同场景（欢迎、学习、练习、反馈、进度、对话）
• 带动作处理的交互组件
• ContentModel 到 ComponentNode 的渲染流程

运行示例：

cd examples/basic-demo
npm install
npm run dev

🛠️ 开发

设置

# 安装依赖
pnpm install

# 构建库
pnpm run build

# 运行类型检查
pnpm run type-check

# 代码检查
pnpm run lint

# 格式化代码
pnpm run format

项目结构

zhama/a2ui/
├── src/
│   ├── types/          # TypeScript 类型定义
│   ├── data/           # 数据结构和工具
│   ├── events/         # 事件处理
│   ├── ui/             # React 组件
│   ├── context/        # React context 提供者
│   ├── styles/         # CSS 和主题定义
│   └── index.ts        # 主入口点
├── examples/           # 示例应用
│   └── basic-demo/     # 完整功能演示
├── dist/               # 构建输出
└── README.md

🤝 贡献

我们欢迎贡献！请遵循以下指南：

1. Fork 仓库
2. 创建 特性分支 (git checkout -b feature/amazing-feature)
3. 提交 你的更改 (git commit -m 'Add amazing feature')
4. 推送 到分支 (git push origin feature/amazing-feature)
5. 打开 Pull Request

开发指南

• 编写清晰、自文档化的代码
• 遵循现有代码风格（由 ESLint/Prettier 强制执行）
• 为新功能添加测试
• 根据需要更新文档
• 提交 PR 前确保所有测试通过

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

🙏 致谢

• 受 Google 的 A2UI 协议启发
• 使用 React 和 TypeScript 构建

📞 支持

• 🐛 问题反馈: GitHub Issues
• 💬 讨论: GitHub Discussions
• 📧 邮箱: [email protected]

❓ 常见问题

A2UI 组件专为 AI 智能体动态生成而设计，而非手动编码。它使用基于协议的方法，AI 输出结构化数据（ContentModel）并渲染为 UI，而非 AI 生成组件代码。

可以！虽然专为 AI 驱动的 UI 设计，你也可以手动创建 ComponentNode 结构并使用 A2UIRoot 渲染。只是比传统 React 开发更繁琐。

A2UI 是协议优先，专为 AI 生成设计。shadcn/ui 是开发者优先，专为手动编码设计。你可以同时使用 - A2UI 用于 AI 生成内容，shadcn 用于开发者构建功能。

任何能输出结构化 JSON 的 LLM 都可以。我们已测试过：

• GPT-4, GPT-3.5-turbo (OpenAI)
• Claude 3 (Anthropic)
• Gemini Pro (Google)
• 通过本地推理的开源模型

可以！A2UI 使用独立的 a2- 前缀 CSS 工具类系统。你可以通过 ThemeProvider 的 theme 属性覆盖默认样式，或覆盖 CSS 变量。

可以！A2UI 稳定且已在生产应用中使用。但作为 v1.0 库，未来版本可能会有小的 API 改进。

Made with ❤️ by Zhama AI

如果你觉得有帮助，请给个 Star ⭐！