{"id":46890713,"url":"https://github.com/southleft/a2ui-bridge","last_synced_at":"2026-03-10T22:39:08.973Z","repository":{"id":330304439,"uuid":"1122031507","full_name":"southleft/a2ui-bridge","owner":"southleft","description":"Framework adapters for Google's A2UI Protocol - LLM-driven UI generation","archived":false,"fork":false,"pushed_at":"2026-01-13T03:09:50.000Z","size":3511,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-13T06:42:40.133Z","etag":null,"topics":["a2ui","ai","designsystems","mcp"],"latest_commit_sha":null,"homepage":"https://a2ui.southleft.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/southleft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-24T01:47:45.000Z","updated_at":"2026-01-13T03:09:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/southleft/a2ui-bridge","commit_stats":null,"previous_names":["southleft/a2ui-bridge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/southleft/a2ui-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/southleft%2Fa2ui-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/southleft%2Fa2ui-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/southleft%2Fa2ui-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/southleft%2Fa2ui-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/southleft","download_url":"https://codeload.github.com/southleft/a2ui-bridge/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/southleft%2Fa2ui-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30359471,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"ssl_error","status_checked_at":"2026-03-10T21:40:59.357Z","response_time":106,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2ui","ai","designsystems","mcp"],"created_at":"2026-03-10T22:39:08.202Z","updated_at":"2026-03-10T22:39:08.949Z","avatar_url":"https://github.com/southleft.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A2UI Bridge\n\n**Let AI agents create real user interfaces using any component library.**\n\nA2UI Bridge implements Google's [A2UI Protocol](https://a2ui.org) for React, enabling AI-generated UIs that render with your existing design system.\n\n## What is A2UI?\n\nA2UI (Agent-to-UI) is a protocol that lets AI agents build user interfaces without writing code. Here's how it works:\n\n1. **You describe what you want** - \"Create a contact card with name, email, and a call button\"\n2. **The AI generates JSON** - It describes the UI structure, not actual code\n3. **A2UI Bridge renders it** - The JSON gets turned into real components from your design system\n\nThe same A2UI JSON can render with **any** component library - Mantine, ShadCN, Material UI, or your own custom components. The AI doesn't need to know React or your specific library.\n\n## Why Use A2UI?\n\n- **Framework-agnostic**: Same AI response works across different component libraries\n- **Secure**: Declarative JSON, not executable code\n- **Real-time**: UI builds progressively as the AI generates it\n- **Native integration**: Uses your existing components with your styling\n\n## Installation\n\n```bash\nnpm install @a2ui-bridge/core @a2ui-bridge/react\n```\n\n## Quick Start\n\n### 1. Create adapters for your components\n\nMap A2UI component types to your actual components:\n\n```tsx\nimport { createAdapter, extractValue } from '@a2ui-bridge/react';\nimport { Button, Text, Card } from '@mantine/core'; // or any library\n\nconst ButtonAdapter = createAdapter(Button, {\n  mapProps: (a2ui, ctx) =\u003e ({\n    children: ctx.renderChild(a2ui.child),\n    onClick: () =\u003e a2ui.action \u0026\u0026 ctx.onAction({ name: a2ui.action.name }),\n  }),\n});\n\nconst TextAdapter = createAdapter(Text, {\n  mapProps: (a2ui) =\u003e ({\n    children: extractValue(a2ui.text),\n    size: extractValue(a2ui.usageHint) === 'h1' ? 'xl' : 'md',\n  }),\n});\n\n// Register all adapters\nconst components = {\n  Button: ButtonAdapter,\n  Text: TextAdapter,\n  Card: CardAdapter,\n  // ... more adapters\n};\n```\n\n### 2. Render A2UI surfaces\n\n```tsx\nimport { Surface, useA2uiProcessor } from '@a2ui-bridge/react';\n\nfunction App() {\n  const processor = useA2uiProcessor();\n\n  // Process A2UI messages from your AI\n  const handleAIResponse = (messages) =\u003e {\n    processor.processMessages(messages);\n  };\n\n  return (\n    \u003cSurface\n      processor={processor}\n      components={components}\n      onAction={(action) =\u003e console.log('User action:', action)}\n    /\u003e\n  );\n}\n```\n\n### 3. Send A2UI messages from your AI\n\n```json\n[\n  {\n    \"beginRendering\": {\n      \"surfaceId\": \"@default\",\n      \"root\": \"greeting-card\"\n    }\n  },\n  {\n    \"surfaceUpdate\": {\n      \"surfaceId\": \"@default\",\n      \"components\": [\n        {\n          \"id\": \"greeting-card\",\n          \"component\": {\n            \"Card\": {\n              \"children\": [\"greeting-text\"]\n            }\n          }\n        },\n        {\n          \"id\": \"greeting-text\",\n          \"component\": {\n            \"Text\": {\n              \"text\": { \"literalString\": \"Hello from A2UI!\" },\n              \"usageHint\": { \"literalString\": \"h2\" }\n            }\n          }\n        }\n      ]\n    }\n  }\n]\n```\n\n## A2UI Protocol Messages\n\n### beginRendering\nStarts a new surface and sets the root component:\n\n```json\n{\n  \"beginRendering\": {\n    \"surfaceId\": \"@default\",\n    \"root\": \"my-component-id\"\n  }\n}\n```\n\n### surfaceUpdate\nUpdates components on the surface:\n\n```json\n{\n  \"surfaceUpdate\": {\n    \"surfaceId\": \"@default\",\n    \"components\": [\n      {\n        \"id\": \"my-button\",\n        \"component\": {\n          \"Button\": {\n            \"child\": \"button-text\",\n            \"action\": { \"name\": \"submit\" }\n          }\n        }\n      }\n    ]\n  }\n}\n```\n\n### dataModelUpdate\nUpdates data for data-bound components:\n\n```json\n{\n  \"dataModelUpdate\": {\n    \"surfaceId\": \"@default\",\n    \"path\": \"/\",\n    \"contents\": [\n      { \"key\": \"user.name\", \"value\": { \"valueString\": \"John\" } }\n    ]\n  }\n}\n```\n\n### deleteSurface\nRemoves a surface:\n\n```json\n{\n  \"deleteSurface\": {\n    \"surfaceId\": \"@default\"\n  }\n}\n```\n\n## Supported Components\n\nBoth design system packages support 70+ components across these categories:\n\n| Category | Components |\n|----------|------------|\n| **Layout** | Row, Column, Flex, Grid, Center, Box, Container, Card, Divider, ScrollArea, AspectRatio |\n| **Typography** | Text, Title, Code, Blockquote, Badge, Label, Link |\n| **Forms** | Button, ActionIcon, TextField, TextArea, Checkbox, Switch, Select, MultiSelect, RadioGroup, Slider, NumberInput |\n| **Feedback** | Alert, Progress, Spinner, Toast, Tooltip |\n| **Navigation** | Tabs, TabPanel, Breadcrumb, Pagination |\n| **Data Display** | List, Table, TableHeader, TableBody, TableRow, TableCell, Avatar, Image, Skeleton |\n| **Disclosure** | Accordion, AccordionItem, Collapsible, Dialog, Sheet, Popover, DropdownMenu, HoverCard |\n\n**Aliases included**: HStack, VStack, Stack, Modal, Drawer, Menu, Loader, IconButton, Heading, H1-H6, and more.\n\n## Data Binding\n\nComponents can bind to data model values:\n\n```json\n{\n  \"TextField\": {\n    \"text\": { \"path\": \"form.email\" },\n    \"label\": { \"literalString\": \"Email\" }\n  }\n}\n```\n\nActions can include context from the data model:\n\n```json\n{\n  \"action\": {\n    \"name\": \"submit-form\",\n    \"context\": [\n      { \"key\": \"email\", \"value\": { \"path\": \"form.email\" } }\n    ]\n  }\n}\n```\n\n## Packages\n\n| Package | Description |\n|---------|-------------|\n| `@a2ui-bridge/core` | Protocol processing, state management, data binding |\n| `@a2ui-bridge/react` | React adapter with hooks and Surface component |\n| `@a2ui-bridge/react-mantine` | **77 adapters** for Mantine UI components |\n| `@a2ui-bridge/react-shadcn` | **76 adapters** for ShadCN/Tailwind components |\n\n### Design System Adapters\n\nA2UI Bridge ships with two complete design system adapters you can use out of the box:\n\n```bash\n# Using Mantine (recommended for enterprise)\nnpm install @a2ui-bridge/react-mantine @mantine/core @mantine/hooks\n\n# Using ShadCN/Tailwind (recommended for custom styling)\nnpm install @a2ui-bridge/react-shadcn\n```\n\n```tsx\n// Mantine\nimport { mantineComponents } from '@a2ui-bridge/react-mantine';\n\u003cSurface components={mantineComponents} ... /\u003e\n\n// ShadCN/Tailwind\nimport { shadcnComponents } from '@a2ui-bridge/react-shadcn';\n\u003cSurface components={shadcnComponents} ... /\u003e\n```\n\nBoth packages support 70+ component types including layouts, forms, navigation, feedback, and data display components.\n\n## Architecture\n\n```\nAI Agent (Claude, GPT, Gemini, etc.)\n              |\n              v\n       A2UI JSON Messages\n              |\n              v\n    +------------------+\n    | @a2ui-bridge/core |  \u003c-- Parses protocol, manages state\n    +------------------+\n              |\n              v\n    +------------------+\n    | @a2ui-bridge/react|  \u003c-- React bindings, Surface component\n    +------------------+\n              |\n    +---------+---------+\n    |                   |\n    v                   v\n+----------------------+  +---------------------+\n| react-mantine (77)   |  | react-shadcn (76)   |\n| Mantine adapters     |  | Tailwind adapters   |\n+----------------------+  +---------------------+\n    |                   |\n    v                   v\n   Mantine UI         ShadCN/Tailwind\n```\n\n## Demo\n\n**[Try the live demo](https://a2ui.southleft.com/demo)** - Describe any UI and watch it render in real-time.\n\nOr run it locally:\n\n```bash\ncd apps/demo\ncp .env.example .env  # Add your Anthropic API key\npnpm install\npnpm run dev\n```\n\nVisit http://localhost:5173 to start generating UIs. You can also enter your API key directly in the demo UI.\n\n### Demo Features\n\n- **Design System Switcher**: Toggle between Mantine and ShadCN in real-time to see the same UI rendered with different component libraries\n- **Multi-Provider Support**: Switch between Anthropic Claude, OpenAI GPT, and Google Gemini\n- **Streaming Progress**: Real-time feedback with stage indicators, elapsed time, and cancel capability\n- **Error Recovery**: Graceful error boundaries prevent crashes and enable retry\n- **Configuration System**: Centralized, validated configuration with environment variable support\n- **Protocol Viewer**: See the A2UI JSON being generated in real-time\n\nSee [apps/demo/README.md](apps/demo/README.md) for detailed documentation.\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm run build\n\n# Run demo\ncd apps/demo \u0026\u0026 pnpm run dev\n```\n\n## Resources\n\n- [A2UI Protocol Specification](https://a2ui.org)\n- [A2UI GitHub](https://github.com/nicholaspetrov/a2ui)\n- [Mantine Components](https://mantine.dev) - Enterprise-ready React components\n- [ShadCN UI](https://ui.shadcn.com) - Beautifully designed Tailwind components\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsouthleft%2Fa2ui-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsouthleft%2Fa2ui-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsouthleft%2Fa2ui-bridge/lists"}