Frontend Architecture
This document defines Zakardo’s frontend architecture: the A2UI (Agent-to-User Interface) rendering system, the surface model, the component catalog, the streaming consumption pipeline, and how the frontend integrates with the Zakardo Runtime via the SDK. It covers how agent-generated UI is rendered, how developers customize the experience, and how the frontend handles the full intent lifecycle from submission to result display.
Prerequisites: This document assumes familiarity with Full-Stack Framework, Capability System (especially §7 Interaction Spec and §8 Anchored Views), Runtime API and SDK (especially §4 SSE and §15 Client SDK), Execution Engine, and Plan IR.
1. Design Goals
Section titled “1. Design Goals”- Agent-driven, developer-owned. The agent decides what to show (via A2UI messages). The developer controls how it looks (via the component catalog and theme system).
- Surfaces, not pages. A2UI renders into named surfaces — regions of the application where agent content appears. Surfaces are declared by the developer and targeted by the agent.
- Two view modes. Anchored Views provide product-quality, pre-designed experiences for common outputs. Ephemeral Views are dynamically composed for everything else. The developer can incrementally upgrade views from ephemeral to anchored.
- Streaming-first. The frontend consumes SSE events progressively. Every phase of the intent lifecycle (planning, approval, execution, result) renders incrementally — never a spinner followed by a full-page dump.
- Framework-agnostic core. The A2UI rendering engine (
@zakardo/a2ui) is framework-agnostic. React bindings (@zakardo/a2ui-react) are provided first-party. Vue, Angular, and Svelte bindings are possible. - Themeable. Components use a design token system. Developers apply their existing design system rather than adapting to Zakardo’s styling.
- Type-safe end-to-end. A2UI messages are typed. Component props are typed. Data bindings between capability output and component props are validated at build time.
2. Surface Model
Section titled “2. Surface Model”2.1 What is a Surface?
Section titled “2.1 What is a Surface?”A Surface is a named region of the frontend where A2UI content is rendered. The developer declares surfaces when mounting the A2UI provider:
import { ZakardoProvider, Surface } from '@zakardo/a2ui-react';
function App() { return ( <ZakardoProvider client={zakardoClient}> <AppLayout> {/* Sidebar: the "assistant" surface — chat-like agent interaction */} <Sidebar> <Surface name="assistant" /> </Sidebar>
{/* Main content: the "workspace" surface — rich data views */} <MainContent> <Surface name="workspace" /> </MainContent>
{/* Notification area: the "notification" surface — toasts and alerts */} <Surface name="notification" position="top-right" /> </AppLayout> </ZakardoProvider> );}2.2 Built-in Surface Types
Section titled “2.2 Built-in Surface Types”| Surface | Purpose | Typical Placement | Content |
|---|---|---|---|
assistant | Conversational agent interface | Sidebar, drawer, or floating panel | Chat messages, plan previews, approvals, clarification prompts |
workspace | Rich data views | Main content area | Data tables, dashboards, detail views, forms |
notification | Transient notifications | Toast/snackbar area | Success messages, warnings, errors |
Developers can define custom surfaces for domain-specific needs:
<Surface name="deal-pipeline" /><Surface name="customer-360" />2.3 Surface Targeting
Section titled “2.3 Surface Targeting”When the Execution Engine completes a step and A2UI Composition generates messages, each message targets a specific surface:
// A2UI message (from SSE stream){ type: 'a2ui', surface: 'workspace', // ← target surface action: 'render', // render | update | clear tree_id: 'tree_abc123', // unique identifier for this component tree components: [...] // component tree to render}Messages targeting a surface that doesn’t exist are silently ignored (logged in development mode).
2.4 Surface Actions
Section titled “2.4 Surface Actions”| Action | Behavior |
|---|---|
render | Replace the surface content with the new component tree |
update | Patch the existing component tree (partial update) |
append | Append content below existing content (chat-style) |
clear | Clear the surface |
3. A2UI Message Format
Section titled “3. A2UI Message Format”3.1 Message Envelope
Section titled “3.1 Message Envelope”Every A2UI message follows this structure:
interface A2UIMessage { /** Message type */ type: 'a2ui';
/** Target surface */ surface: string;
/** Action to perform on the surface */ action: 'render' | 'update' | 'append' | 'clear';
/** Unique identifier for this component tree (for update/clear targeting) */ tree_id: string;
/** The component tree to render (absent for 'clear' action) */ components?: A2UINode[];
/** Data context for data binding */ data?: Record<string, unknown>;
/** Metadata (execution context) */ meta?: { execution_id: string; step_index?: number; capability?: string; view_type: 'anchored' | 'ephemeral'; };}3.2 A2UI Node
Section titled “3.2 A2UI Node”Each node in the component tree:
interface A2UINode { /** Unique node ID within this tree */ id: string;
/** Component reference: { ComponentName: props } */ component: Record<string, Record<string, unknown>>;
/** Optional child node IDs (for layout components) */ children?: string[];}3.3 Data Binding
Section titled “3.3 Data Binding”Component props can reference capability output data via dataPath expressions:
{ "id": "deal_count", "component": { "Metric": { "label": "Open Deals", "value": { "dataPath": "/deals/length" }, "format": "number" } }}The dataPath is a JSON Pointer (RFC 6901) into the data field of the A2UI message. Data binding is resolved by the A2UI renderer at render time.
4. Component Catalog
Section titled “4. Component Catalog”4.1 Overview
Section titled “4.1 Overview”Components are the building blocks of A2UI views. Every component referenced in an A2UI message must be registered in a catalog. Zakardo ships a Standard Catalog with common components. Developers extend it with custom components via packages/catalog.
4.2 Zakardo Standard Catalog
Section titled “4.2 Zakardo Standard Catalog”The Standard Catalog (@zakardo/a2ui/catalog) ships with components for the most common data presentations:
Layout Components
Section titled “Layout Components”| Component | Description | Key Props |
|---|---|---|
Column | Vertical stack | gap, children |
Row | Horizontal stack | gap, align, children |
Grid | CSS Grid layout | columns, gap, children |
Card | Bordered container with optional header/footer | title, subtitle, children |
Tabs | Tabbed container | tabs: [{ label, children }] |
Accordion | Collapsible sections | sections: [{ title, children }] |
Divider | Horizontal rule | label |
Data Display Components
Section titled “Data Display Components”| Component | Description | Key Props |
|---|---|---|
DataTable | Sortable, filterable table | columns, data, sortable, filterable, pageSize |
DetailList | Key-value pair list | items: [{ label, value }] |
Metric | Single metric display | label, value, format, trend |
MetricRow | Row of metrics | metrics: [{ label, value, format }] |
StatusBadge | Colored status indicator | text, status (success, warning, error, info, neutral) |
ProgressBar | Progress indicator | value, max, label |
Timeline | Chronological event list | events: [{ time, title, description }] |
CodeBlock | Syntax-highlighted code | language, code |
JsonView | Interactive JSON tree | data |
Interactive Components
Section titled “Interactive Components”| Component | Description | Key Props |
|---|---|---|
Button | Clickable action button | label, action, variant |
Form | Form with validation | fields, onSubmit |
TextInput | Text input field | label, placeholder, value |
Select | Dropdown selector | label, options, value |
Checkbox | Boolean toggle | label, checked |
Confirm | Confirmation dialog | title, message, confirmLabel, cancelLabel |
Content Components
Section titled “Content Components”| Component | Description | Key Props |
|---|---|---|
Text | Rich text (Markdown) | content, variant (body, heading, caption) |
Alert | Colored alert banner | type (info, success, warning, error), title, message |
Empty | Empty state placeholder | icon, title, description, action |
Loading | Loading skeleton | lines, variant |
Image | Image display | src, alt, width, height |
4.3 Custom Catalog
Section titled “4.3 Custom Catalog”Developers create custom components in packages/catalog for domain-specific visualizations:
import { defineA2UIComponent } from '@zakardo/a2ui';
export default defineA2UIComponent({ name: 'DealPipeline', description: 'Kanban board visualization for deal stages',
propsSchema: { stages: { type: 'array', items: { type: 'string' }, required: true }, deals: { type: 'array', items: { type: 'object' }, required: true }, onDealClick: { type: 'action', required: false }, },
// React implementation render: 'DealPipelineRenderer',});import type { A2UIComponentProps } from '@zakardo/a2ui-react';
export function DealPipelineRenderer({ stages, deals, onDealClick,}: A2UIComponentProps<'DealPipeline'>) { return ( <div className="deal-pipeline"> {stages.map((stage) => ( <div key={stage} className="pipeline-column"> <h3>{stage}</h3> {deals .filter((d) => d.stage === stage) .map((deal) => ( <div key={deal.id} className="deal-card" onClick={() => onDealClick?.(deal)}> <strong>{deal.name}</strong> <span>${deal.value.toLocaleString()}</span> </div> ))} </div> ))} </div> );}4.4 Catalog Registration
Section titled “4.4 Catalog Registration”Custom catalogs are registered in packages/catalog/src/catalog.ts:
import { defineCatalog } from '@zakardo/a2ui';import DealPipeline from './components/DealPipeline';import CustomerCard from './components/CustomerCard';
export default defineCatalog({ name: 'my-crm-catalog', extends: 'zakardo-standard', // Inherit all standard components
components: { DealPipeline, CustomerCard, },});4.5 Catalog Resolution
Section titled “4.5 Catalog Resolution”When the A2UI renderer encounters a component reference, it resolves it in this order:
- Custom catalog (
packages/catalog) — if the capability’sanchored_view.catalogor the project config specifies a custom catalog. - Zakardo Standard Catalog — the default fallback.
If a component is not found in any catalog, the renderer displays an error boundary in development and a fallback Text component in production.
5. View Composition
Section titled “5. View Composition”5.1 Anchored Views
Section titled “5.1 Anchored Views”Anchored Views are pre-designed component trees declared on capabilities (see Capability System §8). They provide product-quality, pixel-perfect rendering for frequently-used outputs.
When a step completes and it has an Anchored View:
- A2UI Composition loads the Anchored View’s component tree from the capability definition.
- Resolves all
dataPathbindings against the capability’s output data. - Emits an A2UI message targeting the declared surface with
meta.view_type: 'anchored'.
Example — “Show open deals” capability with Anchored View:
User: "Show me all open deals" → Planner → Plan (1 step: list_open_deals) → Execution → list_open_deals completes → output: { deals: [...], summary: { total: 12 } } → A2UI Composition detects anchored_view on list_open_deals → Loads pre-defined DataTable + MetricRow layout → Binds /deals → DataTable.data, /summary/total_label → Metric.value → Emits A2UI message → surface: "workspace" → Frontend renders polished deals dashboard5.2 Ephemeral Views
Section titled “5.2 Ephemeral Views”When a capability does not have an Anchored View, A2UI Composition dynamically assembles a view from the capability’s output schema:
- Inspects the output data shape.
- Selects appropriate Standard Catalog components:
- Array of objects →
DataTable - Single object →
DetailList - Scalar →
Metric - Nested →
Cardwith recursion
- Array of objects →
- Applies default layout (
Columnwrapper). - Emits the A2UI message with
meta.view_type: 'ephemeral'.
Ephemeral Views are “good enough” for most outputs. Developers can upgrade any ephemeral view to an Anchored View by adding an anchored_view declaration to the capability.
5.3 Assistant Surface Messages
Section titled “5.3 Assistant Surface Messages”The assistant surface (chat-style) receives a different class of A2UI messages:
| Event | Assistant Surface Rendering |
|---|---|
intent.received | Shown as user message bubble |
planner.thinking | Loading indicator with “Planning…” |
planner.clarification | Question card with options |
planner.conversation | Agent response bubble |
plan.awaiting_approval | Plan Review card (see §6) |
execution.step_started | Progress indicator |
execution.step_completed | Step completion checkmark |
execution.gate_triggered | Gate approval card |
execution.completed | Success message with link to workspace view |
execution.failed | Error card with trace link |
6. Intent Lifecycle Rendering
Section titled “6. Intent Lifecycle Rendering”6.1 Overview
Section titled “6.1 Overview”The frontend renders the full intent lifecycle progressively via SSE events. Each phase of the lifecycle maps to specific UI states:
Intent Submitted → Show user message + loading │ ▼Planning → Show "Planning..." indicator │ ├── CLARIFY → Show question + options (user responds) ├── CONVERSE → Show agent response (no plan) │ ▼Plan Generated → Show plan steps as a checklist │ ▼Awaiting Approval → Show Plan Review card with approve/reject │ ├── Rejected → Show rejection message │ ▼Execution Started → Animate plan steps: ◯→●→✓ │ ├── Gate → Show gate approval UI ├── Interaction → Show interaction form ├── Retry → Show retry status │ ▼Execution Complete → Show success + results (workspace surface)6.2 Plan Review Card
Section titled “6.2 Plan Review Card”When a plan requires approval (plan.awaiting_approval), the assistant surface shows a Plan Review card:
// Rendered by the SDK's React hooks<PlanReview plan={{ steps: [ { index: 0, capability: 'list_customers', description: 'List all churned customers', effectClass: 'READ' }, { index: 1, capability: 'send_email_batch', description: 'Send recovery email', effectClass: 'WRITE_EXTERNAL' }, ], summary: 'This plan will find all churned customers and send them a recovery email.', effectSummary: 'READ (1 step), WRITE_EXTERNAL (1 step)', estimatedDuration: 5000, }} validationResult={{ valid: true, checks: [...] }} onApprove={() => stream.approve()} onReject={(reason) => stream.reject(reason)}/>The Plan Review card shows:
- Step list — each step with its capability name, description, and effect class (color-coded).
- Effect summary — aggregated risk level.
- Validator results — pass/fail checks from the Validator (see Validator Specification §6.2).
- Estimated duration — from Plan IR metadata.
- Approve/Reject buttons.
6.3 Gate Approval UI
Section titled “6.3 Gate Approval UI”When a gate is triggered during execution (execution.gate_triggered):
<GateApproval gate={{ gateId: 'gate_step2_write', stepIndex: 1, capability: 'send_email_batch', reason: 'WRITE_EXTERNAL capability requires approval', approverRoles: ['manager', 'admin'], }} onApprove={(comment) => client.respondToGate(executionId, gate.gateId, 'approve', comment)} onDeny={(comment) => client.respondToGate(executionId, gate.gateId, 'deny', comment)}/>6.4 Interaction UI
Section titled “6.4 Interaction UI”When a capability requires user input (execution.interaction_required):
<InteractionForm interaction={{ stepIndex: 2, capability: 'select_pricing_tier', formSchema: { fields: [ { name: 'tier', type: 'select', label: 'Pricing Tier', options: ['basic', 'pro', 'enterprise'], }, { name: 'confirmed', type: 'checkbox', label: 'I confirm this selection' }, ], }, context: 'The customer is eligible for all pricing tiers. Please select one.', }} onSubmit={(response) => client.respondToInteraction(executionId, 2, response)}/>The form schema is derived from the capability’s Interaction Spec (see Capability System §7).
7. React Integration
Section titled “7. React Integration”7.1 Package: @zakardo/a2ui-react
Section titled “7.1 Package: @zakardo/a2ui-react”The React integration provides hooks, components, and context for rendering A2UI content in React applications:
npm install @zakardo/a2ui-react7.2 Provider
Section titled “7.2 Provider”import { ZakardoProvider } from '@zakardo/a2ui-react';import { ZakardoClient } from '@zakardo/sdk';import catalog from '@my-app/catalog';
const client = new ZakardoClient({ baseUrl: '/zakardo/v1',});
function App() { return ( <ZakardoProvider client={client} catalog={catalog}> <MyApp /> </ZakardoProvider> );}7.3 Hooks
Section titled “7.3 Hooks”useZakardoIntent
Section titled “useZakardoIntent”Manages the full intent lifecycle:
const { submit, // (request: IntentRequest) => void status, // 'idle' | 'planning' | 'awaiting_approval' | 'executing' | 'completed' | 'failed' stream, // Stream controller (approve, reject, cancel) plan, // Plan data (when status is 'awaiting_approval') steps, // Step progress array (during execution) result, // Execution result (when completed) error, // Error (when failed) a2uiMessages, // Array of A2UI messages received} = useZakardoIntent();useZakardoExecution
Section titled “useZakardoExecution”Subscribes to an existing execution’s progress:
const { status, steps, events, result, a2uiMessages } = useZakardoExecution(executionId);useA2UISurface
Section titled “useA2UISurface”Accesses the current content state for a specific surface:
const { trees, // Active component trees on this surface lastUpdate, // Timestamp of last update} = useA2UISurface('workspace');7.4 Components
Section titled “7.4 Components”<Surface>
Section titled “<Surface>”Renders all A2UI content targeted at a named surface:
<Surface name="workspace" fallback={<EmptyWorkspace />} // Shown when surface has no content className="my-workspace" // Custom CSS class/><A2UIRenderer>
Section titled “<A2UIRenderer>”Renders a specific A2UI component tree:
<A2UIRenderer tree={a2uiMessage.components} data={a2uiMessage.data} catalog={catalog} /><ChatAssistant>
Section titled “<ChatAssistant>”Pre-built assistant surface with chat UI:
<ChatAssistant placeholder="Ask me anything..." onSubmit={(message) => intent.submit({ message })} showPlanPreview={true} showExecutionProgress={true}/>This is a convenience component that combines <Surface name="assistant"> with an input field, message history, plan review cards, and execution progress. It can be used as-is or as a reference for custom implementations.
8. Theming
Section titled “8. Theming”8.1 Design Token System
Section titled “8.1 Design Token System”A2UI components use CSS custom properties (design tokens) for all visual properties. Developers override tokens to apply their design system:
/* Base theme (shipped with @zakardo/a2ui) */:root { --z-color-bg: #ffffff; --z-color-bg-secondary: #f9fafb; --z-color-text: #111827; --z-color-text-secondary: #6b7280; --z-color-border: #e5e7eb; --z-color-primary: #3b82f6; --z-color-success: #10b981; --z-color-warning: #f59e0b; --z-color-error: #ef4444; --z-font-family: 'Inter', system-ui, sans-serif; --z-font-size-sm: 0.875rem; --z-font-size-base: 1rem; --z-font-size-lg: 1.125rem; --z-radius-sm: 0.375rem; --z-radius-md: 0.5rem; --z-radius-lg: 0.75rem; --z-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05); --z-shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07); --z-spacing-xs: 0.25rem; --z-spacing-sm: 0.5rem; --z-spacing-md: 1rem; --z-spacing-lg: 1.5rem;}8.2 Dark Mode
Section titled “8.2 Dark Mode”A2UI ships with built-in dark mode via a .zakardo-dark class on the provider:
<ZakardoProvider client={client} theme="dark"> <MyApp /></ZakardoProvider>Or auto-detect from the system preference:
<ZakardoProvider client={client} theme="auto">8.3 Custom Theme
Section titled “8.3 Custom Theme”import { defineTheme } from '@zakardo/a2ui';
const myTheme = defineTheme({ colors: { primary: '#6366f1', // Indigo success: '#22c55e', bg: '#0f172a', // Slate-900 text: '#f1f5f9', // Slate-100 }, fonts: { family: "'JetBrains Mono', monospace", }, radius: { md: '0.25rem', // Sharper corners },});
<ZakardoProvider client={client} theme={myTheme}>9. Packaged Actions
Section titled “9. Packaged Actions”9.1 What Are Packaged Actions?
Section titled “9.1 What Are Packaged Actions?”Packaged Actions are pre-built, one-click actions that bypass the expressed intent flow. They appear as buttons, quick actions, or context menu items in the frontend:
┌─────────────────────────────────────────┐│ Quick Actions ││ ┌──────────┐ ┌──────────┐ ││ │ + Customer│ │ New Deal │ ││ └──────────┘ └──────────┘ ││ ┌──────────┐ ┌──────────┐ ││ │Send Report│ │ Run Sync │ ││ └──────────┘ └──────────┘ │└─────────────────────────────────────────┘9.2 Registration
Section titled “9.2 Registration”Packaged Actions are defined via the SDK’s configuration:
import { definePackagedActions } from '@zakardo/a2ui-react';
export const quickActions = definePackagedActions([ { id: 'quick_create_customer', label: 'New Customer', icon: 'user-plus', description: 'Create a new customer record', action: { action_id: 'quick_create_customer', // Parameters can be pre-filled or collected via a form parameterForm: { fields: [ { name: 'name', type: 'text', label: 'Name', required: true }, { name: 'email', type: 'email', label: 'Email', required: true }, ], }, }, placement: ['sidebar', 'command-palette'], },]);9.3 Discovery
Section titled “9.3 Discovery”The frontend discovers available packaged actions via:
- Static registration (above) — developer-defined in the frontend codebase.
- Runtime API — capabilities that declare
packaged_actionconfigurations are discoverable viaGET /zakardo/v1/capabilities?packaged=true.
9.4 Execution
Section titled “9.4 Execution”When the user clicks a packaged action:
- If the action has
parameterForm, show the form first. - Submit as a
packagedmode intent to the Runtime API. - Follow the standard SSE lifecycle (planning is skipped — packaged actions map directly to known capabilities).
10. Streaming Architecture
Section titled “10. Streaming Architecture”10.1 SSE Consumption Pipeline
Section titled “10.1 SSE Consumption Pipeline”The frontend consumes SSE events through a layered pipeline:
SSE Connection (EventSource or SDK) │ ▼Event Router ← Routes events by type │ ├── Intent events → Intent State Machine ├── Planner events → Planner State ├── Execution events → Execution State Machine ├── A2UI events → Surface Router └── Error events → Error Handler
Surface Router │ ├── assistant surface → Chat message stream ├── workspace surface → A2UI Renderer └── notification → Toast notifications10.2 Reconnection
Section titled “10.2 Reconnection”SSE reconnection is handled automatically by the SDK:
- Browser
EventSourceauto-reconnects withLast-Event-ID. - The SDK reconnects SSE with the last received
event_id. - Server replays missed events from the Event Store (see Execution Engine §4.5).
- State machines reconcile replayed events with current state.
For non-SSE clients (mobile, CLI), the SDK falls back to the polling endpoint (GET /executions/:id/events, see Runtime API §5.6).
10.3 Optimistic UI
Section titled “10.3 Optimistic UI”For interactive actions (gate approvals, interaction responses), the frontend applies optimistic updates:
- User clicks “Approve” on a gate.
- Frontend immediately shows “Approved” state.
- SDK sends
POST /executions/:id/gate/:gateIdin the background. - If the server returns an error, the frontend reverts to the previous state and shows an error.
11. Frontend Project Structure
Section titled “11. Frontend Project Structure”11.1 apps/web
Section titled “11.1 apps/web”apps/web/├── src/│ ├── main.tsx # React entry point│ ├── App.tsx # Root component (Provider, Surface layout)│ ├── components/│ │ ├── layout/│ │ │ ├── AppLayout.tsx # Main layout (sidebar + workspace)│ │ │ ├── Sidebar.tsx│ │ │ └── Header.tsx│ │ ├── assistant/│ │ │ ├── ChatPanel.tsx # Custom assistant surface implementation│ │ │ ├── MessageList.tsx│ │ │ └── InputBar.tsx│ │ ├── workspace/│ │ │ └── WorkspaceView.tsx # Custom workspace surface wrapper│ │ └── foundation/ # Non-Zakardo pages (billing, admin, etc.)│ │ ├── Dashboard.tsx│ │ └── Settings.tsx│ ├── styles/│ │ ├── theme.css # Design token overrides│ │ └── global.css│ ├── config/│ │ ├── zakardo-client.ts # SDK client initialization│ │ └── packaged-actions.ts # Packaged action definitions│ └── router.tsx # React Router config├── public/├── index.html├── vite.config.ts├── package.json└── tsconfig.json11.2 packages/catalog
Section titled “11.2 packages/catalog”packages/catalog/├── src/│ ├── components/│ │ ├── DealPipeline.ts # Component definition│ │ ├── DealPipelineRenderer.tsx # React renderer│ │ ├── CustomerCard.ts│ │ ├── CustomerCardRenderer.tsx│ │ └── index.ts│ ├── catalog.ts # Catalog registration│ └── index.ts├── package.json└── tsconfig.json12. Accessibility
Section titled “12. Accessibility”12.1 Requirements
Section titled “12.1 Requirements”All A2UI components in the Standard Catalog meet WCAG 2.1 AA standards:
| Requirement | Implementation |
|---|---|
| Keyboard navigation | All interactive components (buttons, forms, tables) are keyboard-accessible |
| Screen readers | ARIA labels, roles, and live regions for dynamic content |
| Focus management | Focus moves logically when surfaces update |
| Color contrast | All token-based colors meet 4.5:1 contrast ratio |
| Motion reduction | Respects prefers-reduced-motion media query |
12.2 Dynamic Content
Section titled “12.2 Dynamic Content”When A2UI messages update a surface, the renderer:
- Uses
aria-live="polite"regions for non-critical updates. - Uses
aria-live="assertive"for error notifications. - Manages focus: new content does not steal focus unless it’s interactive (e.g., gate approval).
13. Performance
Section titled “13. Performance”13.1 Rendering Optimization
Section titled “13.1 Rendering Optimization”| Optimization | How |
|---|---|
| Tree diffing | A2UI renderer diffs component trees (by id). Only changed nodes re-render. |
| Lazy catalog loading | Custom catalog components are code-split. Standard Catalog is tree-shaken. |
| Virtualization | DataTable with 1000+ rows uses virtual scrolling. |
| Memoization | Data binding resolution is memoized per tree_id + data hash. |
13.2 Bundle Size Targets
Section titled “13.2 Bundle Size Targets”| Package | Target Size (gzipped) |
|---|---|
@zakardo/a2ui (core) | < 15 KB |
@zakardo/a2ui-react (bindings) | < 8 KB |
| Standard Catalog (all components) | < 40 KB |
| Standard Catalog (tree-shaken, typical) | < 20 KB |
14. Summary of Decisions
Section titled “14. Summary of Decisions”| Decision | Resolution |
|---|---|
| Surface model | Named regions where A2UI content renders. Developer declares surfaces; agent targets them. Not route-based — multiple surfaces can be active simultaneously. |
| Two view modes | Anchored Views (pre-designed, product quality) and Ephemeral Views (dynamically composed, good enough). Developers incrementally upgrade. |
| Component catalog | Standard Catalog ships with 25+ components. Developers extend with custom catalog in packages/catalog. Catalogs are composable. |
| Framework-agnostic core | @zakardo/a2ui is pure TypeScript. @zakardo/a2ui-react provides React bindings. Other framework bindings are possible. |
| Design token theming | CSS custom properties for all visual properties. Dark mode built-in. Custom themes via defineTheme. |
| Chat-style assistant | The assistant surface is chat-oriented with progressive rendering. Plan previews, gate approvals, and interactions render inline. |
| Streaming-first | All rendering is SSE-driven. No full-page loads. Every lifecycle phase renders incrementally. |
| Optimistic UI | Interactive actions (approve, deny, respond) are optimistic. Server errors trigger rollback. |
| Packaged Actions | One-click shortcuts that bypass expressed intent. Defined in frontend or discovered from capabilities. |
| Accessibility | WCAG 2.1 AA compliance for all Standard Catalog components. |
15. Questions Deferred
Section titled “15. Questions Deferred”| Question | Deferred To |
|---|---|
| How do A2UI components handle real-time data updates (live dashboards)? | Real-time Data Specification (future) |
| How are A2UI components tested in isolation? | Testing and Validation Specification (addendum) |
| How does the mobile SDK render A2UI on native platforms? | Mobile SDK Specification |
| What are the exact animation specifications for transitions? | Implementation detail |
| How does A2UI handle multi-tenant branding? | PRD — Zakardo Cloud |
| How does the registry marketplace distribute custom catalogs? | Registry and Marketplace Specification |