Ballmac UI is an accessible component library for React 19 and Tailwind CSS v4, where components, blocks, and templates share the same design language. It is installed via the shadcn CLI, and the source code goes directly into your project, making it easy to read and modify; it also provides an MCP server so AI coding assistants can search for and install these components. The project is listed in the official shadcn registry directory. The official website and documentation are at ui.ballmac.com.
Main capabilities
For components, it includes more than 240 components, covering basic primitives, forms, data display, navigation, feedback, motion, backgrounds, text effects, AI interfaces, developer tools, device frames, and desktop-style interfaces.
For blocks and templates, it provides more than 60 blocks and 17 templates, including hero, pricing, dashboards, login, settings, and more, all composed from components.
For themes, it provides 12 themes with a live builder, supporting light and dark modes. Motion is part of the theme, including five preset feels: speed, bounce, displacement, hover, and stagger, and it also provides a reduced-motion fallback. Data and form blocks use a single state prop to show loading, empty, error, submitting, and success states. Platform feel makes each component interact the macOS, iOS, or Windows way, and provides window frames for Tauri and Electron apps.
For standards, every entry comes with examples, keyboard support, reduced-motion handling, RTL support, and a provider that translates its built-in text, as detailed in AUTHORING.md.
For AI agents
Every entry includes a description, when to use and when not to use it, composable objects, and keyboard instructions. It can be accessed via llms.txt, the JSON API, and the @ballmac/mcp server. The MCP server is read-only, requires no account, can search the catalog, return props, keyboard behavior, and source code, give exact install commands, and plan an entire page based on blocks. Configuration for Cursor, VS Code, Windsurf, Codex, and Claude Desktop is described in the MCP documentation and packages/mcp. The official shadcn MCP server can also work with this registry.
Usage
Requires a project already configured with React 19, Tailwind CSS v4, and shadcn (run npx shadcn@latest init, which generates components.json). Both Base UI and Radix styles can be used.
@ballmac is already in the official shadcn registry directory, so no registry configuration is needed. If you are using an older CLI, or need a fixed address, run npx shadcn@latest registry add "@ballmac=https://ui.ballmac.com/r/{name}.json"，或按 URL installation: npx shadcn@latest add https://ui.ballmac.com/r/button.json。可在 Browse and preview all content at ui.ballmac.com/components; see the official website for installation instructions, which also includes the optional Ballmac theme.
The development environment requires Node.js 22 (the version CI runs) and pnpm 10 (the repository has pinned this version; corepack enable will install the correct version, or use npx pnpm@10). The Pro registry is optional: without it, the site builds using only free entries. A11Y_BASE_URL is used to point accessibility scans at an already running site.
Avoiding conflicts
All content is installed into the components/ballmac/ directory, so it will not overwrite your shadcn/ui files.
Installation verification
Release checks install each entry into a brand-new Next.js app, then run type checking and a build.
Use cases
Suitable for frontend development scenarios that need to quickly introduce accessible, modifiable components and page blocks into React + Tailwind projects, and especially suitable for use with AI coding assistants for component search, installation, and page planning.
Limitations and licensing
Pro is a commercial version, licensed separately, and its source code is not in this repository; see ui.ballmac.com/pricing for details and pricing, and ui.ballmac.com/docs/pro for setup instructions. Free components, blocks, templates, and the MCP server are licensed under MIT (see LICENSE), and THIRD_PARTY_NOTICES.md lists the open-source work they depend on. For contribution, support, and security-related notes, see CONTRIBUTING.md, the code of conduct, and SECURITY.md respectively; issues and requests can be submitted via issue, and for questions, purchases, or license key-related support, see ui.ballmac.com/support.
