🎯 Skill Positioning
This skill covers @ant-design/x-card — the React implementation of the A2UI protocol, enabling AI agents to dynamically render rich interactive UIs through structured JSON command streams.
It covers:
XCard.Box + XCard.Card component usage
- A2UI v0.9 command types:
createSurface, updateComponents, updateDataModel, deleteSurface
- Custom component registration and catalog management
- Data binding via JSON Pointer paths (RFC 6901)
- Action handling — sending user events back to the agent
- Streaming progressive rendering patterns
- v0.8 ↔ v0.9 protocol differences
Scope: v0.9 is the recommended protocol. v0.8 is supported for backward compatibility only — prefer v0.9 for all new work.
Table of Contents
📦 Package Overview
| Package |
Responsibility |
@ant-design/x-card |
React renderer for A2UI protocol — XCard.Box, XCard.Card, catalog APIs |
@ant-design/x |
Chat UI components (Bubble, Sender, etc.) — not covered here |
@ant-design/x-sdk |
Data providers, streaming — not covered here |
npm install @ant-design/x-card
Exports:
import {
XCard,
registerCatalog,
loadCatalog,
validateComponent,
clearCatalogCache,
} from '@ant-design/x-card';
import type {
XAgentCommand_v0_9,
XAgentCommand_v0_8,
ActionPayload,
Catalog,
CatalogComponent,
} from '@ant-design/x-card';
// Subcomponents
XCard.Box; // Container: receives commands, owns catalog maps
XCard.Card; // Renderer: renders a single surface by id
🗂️ Component Architecture
XCard.Box
├── owns: catalogMap, surfaceCatalogMap
├── dispatches: commands → all XCard.Card children
├── aggregates: onAction events from all Cards
└── XCard.Card (id="surface-a")
│ ├── owns: component tree, data model, commandVersion
│ └── resolves: data bindings, triggers actions
└── XCard.Card (id="surface-b")
└── ...
XCard.Box Props
interface BoxProps {
commands?: (XAgentCommand_v0_9 | XAgentCommand_v0_8)[];
/** Component names must start with an uppercase letter (React component convention) */
components?: Record<string, React.ComponentType<any>>;
onAction?: (payload: ActionPayload) => void;
children?: React.ReactNode; // Should contain XCard.Card elements
}
XCard.Card Props
interface CardProps {
id: string; // surfaceId to render
}
ActionPayload
interface ActionPayload {
name: string; // from action.event.name
surfaceId: string; // which surface triggered it
/**
* Context passed by component, with path references automatically resolved.
*
* For action.event.context fields using { path: "xxx" } format:
* - X-Card automatically resolves them to { value: "actual_value" }
* - Other properties (like label) are preserved
*
* Example input config:
* { username: { path: "/form/username", label: "用户名" } }
*
* Example resolved context:
* { username: { value: "张三", label: "用户名" } }
*/
context: Record<string, any>;
}
🚀 Quick Start Decision Guide
| If you need to... |
Read first |
| Set up XCard.Box + XCard.Card |
USAGE.md → Basic Setup |
| Send commands from agent to card |
COMMANDS.md |
| Register a custom component catalog |
CATALOG.md → Local Catalog |
| Bind component props to live data |
DATA_BINDING.md |
| Handle user interactions / form submit |
ACTIONS.md |
| Build a streaming progressive UI |
USAGE.md → Streaming |
| Migrate from v0.8 to v0.9 |
COMMANDS.md → v0.8 vs v0.9 |
| Look up full prop types |
API.md |
🛠 Recommended Workflow
- Define your catalog — register a local catalog or use the A2UI Basic Catalog URL.
- Register custom components — pass them via
XCard.Box components prop.
- Create the React tree — wrap surfaces with
XCard.Box, add XCard.Card per surface.
- Feed commands — push
XAgentCommand_v0_9[] into commands prop (typically from streaming agent response).
- Handle actions — receive
ActionPayload in onAction, update commands in response.
Minimal Working Example
import React, { useState } from 'react';
import { XCard, registerCatalog } from '@ant-design/x-card';
import type { XAgentCommand_v0_9, ActionPayload, Catalog } from '@ant-design/x-card';
// 1. Define and register local catalog
const myCatalog: Catalog = {
catalogId: 'local://my_catalog.json',
components: {
Text: {
type: 'object',
properties: { text: { type: 'string' }, variant: { type: 'string' } },
required: ['text'],
},
Button: {
type: 'object',
properties: { text: { type: 'string' }, action: {} },
required: ['text'],
},
},
};
registerCatalog(myCatalog);
// 2. Custom component implementations
const Text: React.FC<{ text: string; variant?: string }> = ({ text, variant }) => (
<p className={`text-${variant ?? 'body'}`}>{text}</p>
);
const Button: React.FC<{ text: string; onAction?: (ctx: any) => void; action?: any }> = ({
text,
onAction,
action,
}) => <button => onAction?.(action?.event?.context ?? {})}>{text}</button>;
// 3. Build commands (from agent stream)
const commands: XAgentCommand_v0_9[] = [
{
version: 'v0.9',
createSurface: {
surfaceId: 'welcome',
catalogId: 'local://my_catalog.json',
},
},
{
version: 'v0.9',
updateComponents: {
surfaceId: 'welcome',
components: [
{ id: 'root', component: 'Column', children: ['title', 'btn'] },
{ id: 'title', component: 'Text', text: { path: '/user/name' }, variant: 'h1' },
{
id: 'btn',
component: 'Button',
text: 'Start',
action: { event: { name: 'start', context: {} } },
},
],
},
},
{
version: 'v0.9',
updateDataModel: {
surfaceId: 'welcome',
path: '/user/name',
value: 'Alice',
},
},
];
// 4. Render
export default function App() {
const [cmdQueue, setCmdQueue] = useState<XAgentCommand_v0_9[]>(commands);
const handleAction = (payload: ActionPayload) => {
console.log('Action:', payload.name, payload.context);
// Append new commands based on agent response
setCmdQueue((prev) => [...prev /* new commands */]);
};
return (
<XCard.Box commands={cmdQueue} components={{ Text, Button }}
<XCard.Card id="welcome" />
</XCard.Box>
);
}
🚨 Development Rules
- Always include
"version": "v0.9" on every command — omitting it causes protocol rejection.
- One and only one
id: "root" component per surface's component tree — this is the tree root.
- Flat adjacency list only — never nest component objects inside other component objects; always reference children by
id string.
- Separate structure from data —
updateComponents for layout, updateDataModel for content/state.
- Register catalog before mounting — call
registerCatalog() before the component tree renders.
- Pass
components map to XCard.Box, not to XCard.Card — Box distributes to all Cards.
- Never recreate the
components object inline — keep it stable with useMemo or module-level constant to avoid re-renders.
- Input components require
value: { path: "..." } for two-way binding — literal values do not update the data model.
- For streaming: append new commands to the array rather than replacing it — Card processes the diff incrementally.
action.event.context paths are write targets — they point to where user-entered data lives in the data model; do not resolve them as read sources.
- Path references in action context are automatically resolved — when an action is triggered, X-Card converts
{ path: "xxx" } in the action config to { value: "actual_value" } in the onAction payload. This works for both v0.9 (action.event.context = { key: { path } }) and v0.8 (action.context = [{ key, value: { path } }]) formats.
🤝 Skill Collaboration
| Scenario |
Skill combination |
| AI chat with structured card responses |
use-x-chat + x-components + x-card |
| Standalone agent form UI |
x-card only |
| Streaming Markdown + card side-panel |
x-markdown + x-card |
| HTTP streaming from agent into card |
x-request → feed response as commands |
🔗 Reference Resources
- USAGE.md — Setup guide, streaming pattern, multi-surface examples
- COMMANDS.md — All four A2UI v0.9 command types, v0.8 vs v0.9 diff
- DATA_BINDING.md — JSON Pointer paths, dynamic types, two-way binding, template iteration
- ACTIONS.md — Action definitions, ActionPayload, form submission pattern
- CATALOG.md — Local catalog registration, remote URL loading, custom component schema
- API.md — Full TypeScript types for Box, Card, commands, catalog, actions
Official Documentation
1---2name: x-card3version: 2.8.14description: Use when building AI-driven UIs with @ant-design/x-card — covers XCard.Box, XCard.Card, A2UI v0.9 commands, data binding, catalogs, actions, and streaming patterns.5metadata:6 source: https://skillmd.com/skills/modelscope/x-card7---89# 🎯 Skill Positioning1011**This skill covers `@ant-design/x-card`** — the React implementation of the A2UI protocol, enabling AI agents to dynamically render rich interactive UIs through structured JSON command streams.1213It covers:1415- `XCard.Box` + `XCard.Card` component usage16- A2UI v0.9 command types: `createSurface`, `updateComponents`, `updateDataModel`, `deleteSurface`17- Custom component registration and catalog management18- Data binding via JSON Pointer paths (RFC 6901)19- Action handling — sending user events back to the agent20- Streaming progressive rendering patterns21- v0.8 ↔ v0.9 protocol differences2223> **Scope**: v0.9 is the recommended protocol. v0.8 is supported for backward compatibility only — prefer v0.9 for all new work.2425## Table of Contents2627- [📦 Package Overview](#-package-overview)28- [🗂️ Component Architecture](#-component-architecture)29- [🚀 Quick Start Decision Guide](#-quick-start-decision-guide)30- [🛠 Recommended Workflow](#-recommended-workflow)31- [🚨 Development Rules](#-development-rules)32- [🤝 Skill Collaboration](#-skill-collaboration)33- [🔗 Reference Resources](#-reference-resources)3435# 📦 Package Overview3637| Package | Responsibility |38| --- | --- |39| `@ant-design/x-card` | React renderer for A2UI protocol — `XCard.Box`, `XCard.Card`, catalog APIs |40| `@ant-design/x` | Chat UI components (Bubble, Sender, etc.) — not covered here |41| `@ant-design/x-sdk` | Data providers, streaming — not covered here |4243```bash44npm install @ant-design/x-card45```4647**Exports:**4849```typescript50import {51 XCard,52 registerCatalog,53 loadCatalog,54 validateComponent,55 clearCatalogCache,56} from '@ant-design/x-card';57import type {58 XAgentCommand_v0_9,59 XAgentCommand_v0_8,60 ActionPayload,61 Catalog,62 CatalogComponent,63} from '@ant-design/x-card';6465// Subcomponents66XCard.Box; // Container: receives commands, owns catalog maps67XCard.Card; // Renderer: renders a single surface by id68```6970# 🗂️ Component Architecture7172```73XCard.Box74├── owns: catalogMap, surfaceCatalogMap75├── dispatches: commands → all XCard.Card children76├── aggregates: onAction events from all Cards77└── XCard.Card (id="surface-a")78│ ├── owns: component tree, data model, commandVersion79│ └── resolves: data bindings, triggers actions80└── XCard.Card (id="surface-b")81 └── ...82```8384## XCard.Box Props8586```typescript87interface BoxProps {88 commands?: (XAgentCommand_v0_9 | XAgentCommand_v0_8)[];89 /** Component names must start with an uppercase letter (React component convention) */90 components?: Record<string, React.ComponentType<any>>;91 onAction?: (payload: ActionPayload) => void;92 children?: React.ReactNode; // Should contain XCard.Card elements93}94```9596## XCard.Card Props9798```typescript99interface CardProps {100 id: string; // surfaceId to render101}102```103104## ActionPayload105106```typescript107interface ActionPayload {108 name: string; // from action.event.name109 surfaceId: string; // which surface triggered it110 /**111 * Context passed by component, with path references automatically resolved.112 *113 * For action.event.context fields using { path: "xxx" } format:114 * - X-Card automatically resolves them to { value: "actual_value" }115 * - Other properties (like label) are preserved116 *117 * Example input config:118 * { username: { path: "/form/username", label: "用户名" } }119 *120 * Example resolved context:121 * { username: { value: "张三", label: "用户名" } }122 */123 context: Record<string, any>;124}125```126127# 🚀 Quick Start Decision Guide128129| If you need to... | Read first |130| --- | --- |131| Set up XCard.Box + XCard.Card | [USAGE.md → Basic Setup](reference/USAGE.md#basic-setup) |132| Send commands from agent to card | [COMMANDS.md](reference/COMMANDS.md) |133| Register a custom component catalog | [CATALOG.md → Local Catalog](reference/CATALOG.md#local-catalog) |134| Bind component props to live data | [DATA_BINDING.md](reference/DATA_BINDING.md) |135| Handle user interactions / form submit | [ACTIONS.md](reference/ACTIONS.md) |136| Build a streaming progressive UI | [USAGE.md → Streaming](reference/USAGE.md#streaming) |137| Migrate from v0.8 to v0.9 | [COMMANDS.md → v0.8 vs v0.9](reference/COMMANDS.md#v08-vs-v09) |138| Look up full prop types | [API.md](reference/API.md) |139140# 🛠 Recommended Workflow1411421. **Define your catalog** — register a local catalog or use the A2UI Basic Catalog URL.1432. **Register custom components** — pass them via `XCard.Box` `components` prop.1443. **Create the React tree** — wrap surfaces with `XCard.Box`, add `XCard.Card` per surface.1454. **Feed commands** — push `XAgentCommand_v0_9[]` into `commands` prop (typically from streaming agent response).1465. **Handle actions** — receive `ActionPayload` in `onAction`, update commands in response.147148## Minimal Working Example149150```tsx151import React, { useState } from 'react';152import { XCard, registerCatalog } from '@ant-design/x-card';153import type { XAgentCommand_v0_9, ActionPayload, Catalog } from '@ant-design/x-card';154155// 1. Define and register local catalog156const myCatalog: Catalog = {157 catalogId: 'local://my_catalog.json',158 components: {159 Text: {160 type: 'object',161 properties: { text: { type: 'string' }, variant: { type: 'string' } },162 required: ['text'],163 },164 Button: {165 type: 'object',166 properties: { text: { type: 'string' }, action: {} },167 required: ['text'],168 },169 },170};171registerCatalog(myCatalog);172173// 2. Custom component implementations174const Text: React.FC<{ text: string; variant?: string }> = ({ text, variant }) => (175 <p className={`text-${variant ?? 'body'}`}>{text}</p>176);177178const Button: React.FC<{ text: string; onAction?: (ctx: any) => void; action?: any }> = ({179 text,180 onAction,181 action,182}) => <button onClick={() => onAction?.(action?.event?.context ?? {})}>{text}</button>;183184// 3. Build commands (from agent stream)185const commands: XAgentCommand_v0_9[] = [186 {187 version: 'v0.9',188 createSurface: {189 surfaceId: 'welcome',190 catalogId: 'local://my_catalog.json',191 },192 },193 {194 version: 'v0.9',195 updateComponents: {196 surfaceId: 'welcome',197 components: [198 { id: 'root', component: 'Column', children: ['title', 'btn'] },199 { id: 'title', component: 'Text', text: { path: '/user/name' }, variant: 'h1' },200 {201 id: 'btn',202 component: 'Button',203 text: 'Start',204 action: { event: { name: 'start', context: {} } },205 },206 ],207 },208 },209 {210 version: 'v0.9',211 updateDataModel: {212 surfaceId: 'welcome',213 path: '/user/name',214 value: 'Alice',215 },216 },217];218219// 4. Render220export default function App() {221 const [cmdQueue, setCmdQueue] = useState<XAgentCommand_v0_9[]>(commands);222223 const handleAction = (payload: ActionPayload) => {224 console.log('Action:', payload.name, payload.context);225 // Append new commands based on agent response226 setCmdQueue((prev) => [...prev /* new commands */]);227 };228229 return (230 <XCard.Box commands={cmdQueue} components={{ Text, Button }} onAction={handleAction}>231 <XCard.Card id="welcome" />232 </XCard.Box>233 );234}235```236237# 🚨 Development Rules238239- **Always include `"version": "v0.9"`** on every command — omitting it causes protocol rejection.240- **One and only one `id: "root"` component** per surface's component tree — this is the tree root.241- **Flat adjacency list only** — never nest component objects inside other component objects; always reference children by `id` string.242- **Separate structure from data** — `updateComponents` for layout, `updateDataModel` for content/state.243- **Register catalog before mounting** — call `registerCatalog()` before the component tree renders.244- **Pass `components` map to `XCard.Box`**, not to `XCard.Card` — Box distributes to all Cards.245- **Never recreate the `components` object inline** — keep it stable with `useMemo` or module-level constant to avoid re-renders.246- **Input components require `value: { path: "..." }` for two-way binding** — literal values do not update the data model.247- **For streaming**: append new commands to the array rather than replacing it — Card processes the diff incrementally.248- **`action.event.context` paths are write targets** — they point to where user-entered data lives in the data model; do not resolve them as read sources.249- **Path references in action context are automatically resolved** — when an action is triggered, X-Card converts `{ path: "xxx" }` in the action config to `{ value: "actual_value" }` in the onAction payload. This works for both v0.9 (`action.event.context = { key: { path } }`) and v0.8 (`action.context = [{ key, value: { path } }]`) formats.250251# 🤝 Skill Collaboration252253| Scenario | Skill combination |254| -------------------------------------- | ---------------------------------------- |255| AI chat with structured card responses | `use-x-chat` + `x-components` + `x-card` |256| Standalone agent form UI | `x-card` only |257| Streaming Markdown + card side-panel | `x-markdown` + `x-card` |258| HTTP streaming from agent into card | `x-request` → feed response as commands |259260# 🔗 Reference Resources261262- [USAGE.md](reference/USAGE.md) — Setup guide, streaming pattern, multi-surface examples263- [COMMANDS.md](reference/COMMANDS.md) — All four A2UI v0.9 command types, v0.8 vs v0.9 diff264- [DATA_BINDING.md](reference/DATA_BINDING.md) — JSON Pointer paths, dynamic types, two-way binding, template iteration265- [ACTIONS.md](reference/ACTIONS.md) — Action definitions, ActionPayload, form submission pattern266- [CATALOG.md](reference/CATALOG.md) — Local catalog registration, remote URL loading, custom component schema267- [API.md](reference/API.md) — Full TypeScript types for Box, Card, commands, catalog, actions268269## Official Documentation270271- [A2UI What Is It](https://a2ui.org/introduction/what-is-a2ui/)272- [A2UI v0.9 Specification](https://a2ui.org/specification/v0.9-a2ui/)273- [Concepts: Data Binding](https://a2ui.org/concepts/data-binding/)274- [Concepts: Catalogs](https://a2ui.org/concepts/catalogs/)275- [Guide: Agent Development](https://a2ui.org/guides/agent-development/)276- [GitHub: google/A2UI](https://github.com/google/A2UI)