Ballmac UI 是一套面向 React 19 与 Tailwind CSS v4 的无障碍组件库，组件、区块和模板共用同一套设计语言。它通过 shadcn CLI 安装，源码直接进入你的项目，方便阅读和修改；同时提供 MCP 服务器，让 AI 编程助手能够搜索并安装这些组件。项目已列入官方 shadcn registry 目录。官网与文档地址为 ui.ballmac.com。
主要能力
组件方面，包含 240 多个组件，涵盖基础原语、表单、数据展示、导航、反馈、动效、背景、文字特效、AI 界面、开发者工具、设备外框以及桌面风格界面。
区块与模板方面，提供 60 多个区块和 17 个模板，包括 hero、定价、仪表盘、登录、设置等，均由组件组合而成。
主题方面，提供 12 套主题并带实时构建器，支持浅色与深色。动效属于主题的一部分，包含速度、回弹、位移、悬停和错落五个预设感觉，并提供减少动效的回退方案。数据与表单区块通过一个 state prop 展示加载、空、错误、提交中和成功状态。平台手感让每个组件按 macOS、iOS 或 Windows 的方式交互，并为 Tauri 和 Electron 应用提供窗口外框。
标准方面，每个条目都配有示例、键盘支持、减少动效处理、RTL 支持，以及为其内置文本提供翻译的 provider，详见 AUTHORING.md。
面向 AI 智能体
每个条目都带有描述、何时使用与何时不使用、可组合对象以及键盘说明。可通过 llms.txt、JSON API 和 @ballmac/mcp 服务器获取。该 MCP 服务器为只读，无需账号，能够搜索目录、返回 props、键盘行为和源码、给出精确安装命令，并可基于区块规划整个页面。Cursor、VS Code、Windsurf、Codex 和 Claude Desktop 的配置方式见 MCP 文档和 packages/mcp。官方 shadcn MCP 服务器也可与此 registry 配合使用。
使用方式
需要已配置 React 19、Tailwind CSS v4 和 shadcn 的项目（运行 npx shadcn@latest init，会生成 components.json）。Base UI 和 Radix 两种风格均可使用。
@ballmac 已在官方 shadcn registry 目录中，因此无需配置 registry。若使用较旧 CLI，或需要固定地址，运行一次 npx shadcn@latest registry add "@ballmac=https://ui.ballmac.com/r/{name}.json"，或按 URL 安装：npx shadcn@latest add https://ui.ballmac.com/r/button.json。可在 ui.ballmac.com/components 浏览和预览全部内容，安装指南见官网，其中也包含可选的 Ballmac 主题。
开发环境需 Node.js 22（CI 所运行版本）和 pnpm 10（仓库已固定该版本；corepack enable 会安装正确版本，或使用 npx pnpm@10）。Pro registry 为可选项：没有它时，站点仅用免费条目构建。A11Y_BASE_URL 用于将无障碍扫描指向已在运行的站点。
避免冲突
所有内容都安装到 components/ballmac/ 目录，因此不会覆盖你的 shadcn/ui 文件。
安装验证
发布检查会把每个条目安装到一个全新的 Next.js 应用中，然后进行类型检查和构建。
适用场景
适用于需要在 React + Tailwind 项目中快速引入可访问、可修改组件与页面区块的前端开发场景，尤其适合配合 AI 编程助手进行组件检索、安装和页面规划。
限制与授权
Pro 为商业版本，单独授权，其源码不在本仓库中；详情与定价见 ui.ballmac.com/pricing，设置方式见 ui.ballmac.com/docs/pro。免费组件、区块、模板和 MCP 服务器采用 MIT 许可（见 LICENSE），THIRD_PARTY_NOTICES.md 中列明了所依赖的开源工作。贡献、支持与安全相关说明分别见 CONTRIBUTING.md、行为准则和 SECURITY.md；问题与请求可通过 issue 提交，问题咨询、购买或许可证密钥相关支持见 ui.ballmac.com/support。
