# Ballmac UI documentation > The full documentation of Ballmac UI (https://ui.ballmac.com/docs) as Markdown. The index of everything else, including every component, block and template, is at https://ui.ballmac.com/llms.txt. # Introduction Ballmac UI is a shadcn registry of accessible React and Tailwind components, blocks and templates that you and your AI agent install as code. Ballmac UI is a collection of React and Tailwind CSS components, blocks and templates: desktop-style app surfaces, living backgrounds, text effects, device frames and AI interfaces. You don't install it as a package. You add the items you need with the shadcn CLI, and the source lands in your project, ready to read and change. ```bash npx shadcn@latest add @ballmac/button ``` Your AI coding agent can do the same through the [Ballmac MCP server](https://ui.ballmac.com/docs/get-started/connect-your-agent) (`@ballmac/mcp`) or the shadcn MCP server. ## Find what you need - [Get started](https://ui.ballmac.com/docs/get-started/install): Install your first component, connect your agent, make it look like your product. - [Guides](https://ui.ballmac.com/docs/guides/update-components): Steps for one task: update components, handle states, turn on right-to-left, set up Pro. - [Reference](https://ui.ballmac.com/docs/reference/cli): Commands, MCP tools, settings, rules and messages, generated from the code. - [Concepts](https://ui.ballmac.com/docs/concepts/how-ballmac-works): Why Ballmac UI works the way it does: ownership, motion, feels, states and quality. ## What makes it different - **Updates that keep your edits.** [The ballmac CLI](https://ui.ballmac.com/docs/guides/update-components) merges new versions into your edited copies and installs the tests that ship with components. - **Quality you can check.** Every item is loaded in a real browser and the [results are public](https://ui.ballmac.com/quality), including failures. [ballmac check](https://ui.ballmac.com/docs/guides/check-your-app) holds your own app to the same bar. - **Native-app polish.** Springs, depth and hairlines from native apps, as app windows, docks, a live notch, menus and notifications that work in any product. - **One design language.** Primitives, effects, AI interfaces and developer components share tokens, spacing, focus states and motion curves, and follow your theme in light and dark. - **Effects with manners.** Globes, beams and particles pause off-screen, stop for reduced motion and keep your page accessible. - **No collisions.** Everything installs into `components/ballmac`, so it never overwrites your shadcn/ui files. Dependencies are declared and checked on every build. - **Made for AI agents.** Every item carries a description, when to use it, when not to, what it composes with and keyboard notes, through MCP and [llms.txt](https://ui.ballmac.com/llms.txt). - **Verified installs.** Each release installs every item into a fresh Next.js app, then type-checks and builds it. ## Free and Pro Every component, block, template and theme is free and MIT licensed. [Ballmac UI Pro](https://ui.ballmac.com/pricing) adds premium blocks, two complete starter apps and the Figma tokens, delivered through a private registry with a licence key. [Set up Pro](https://ui.ballmac.com/docs/guides/pro). ## Requirements - React 19 and Tailwind CSS v4 - A project set up with `shadcn init`, which creates `components.json` and `lib/utils` Stuck, or found a bug? [Contact support](https://ui.ballmac.com/support), or open an issue on [GitHub](https://github.com/vamsiy78/ballmac-ui/issues). --- # Install your first component Add Ballmac UI to a React and Tailwind v4 project and import your first component. It takes about a minute. By the end of this page you have a Ballmac component running in your project. ### Set up shadcn Skip this step if your project already has a `components.json`. Ballmac UI needs React 19 and Tailwind CSS v4. ```bash npx shadcn@latest init ``` ### Add components `@ballmac` is listed in the official shadcn registry directory, so the CLI already knows it. There is nothing to configure. ```bash npx shadcn@latest add @ballmac/button @ballmac/number-ticker ``` Files go to `components/ballmac/`, and the CLI installs the npm packages they need. ### Import and use it ```tsx title="app/page.tsx" import { Button } from "@/components/ballmac/button" export default function Page() { return } ``` Is your project on a Base UI style? Components that use Radix UI also come in a Base UI version, with the same props. [Switch to it](https://ui.ballmac.com/docs/guides/base-ui) when you install. ## Add the Ballmac theme Every component uses the standard shadcn CSS variables, so it follows your existing theme. To match the Ballmac look (neutral light mode, ink-navy dark mode, blue focus ring), add the theme: ```bash npx shadcn@latest add @ballmac/theme ``` ## If the CLI doesn't know @ballmac Recent versions of the shadcn CLI resolve `@ballmac` on their own. If yours doesn't, or you want to pin the address for a mirror or a preview deployment, add the registry once per project: ```bash npx shadcn@latest registry add @ballmac=https://ui.ballmac.com/r/{name}.json ``` It adds this to your `components.json`: ```json title="components.json" { "registries": { "@ballmac": "https://ui.ballmac.com/r/{name}.json" } } ``` > **Note:** The shadcn MCP server only reads `components.json`, so it needs this entry too. You can also install straight from a URL: ```bash npx shadcn@latest add https://ui.ballmac.com/r/button.json ``` ## Next steps - [Connect your AI agent](https://ui.ballmac.com/docs/get-started/connect-your-agent): Let Claude Code, Cursor or VS Code search and install for you. - [Make it yours](https://ui.ballmac.com/docs/get-started/make-it-yours): Apply a theme and set your brand color. - [Update components](https://ui.ballmac.com/docs/guides/update-components): Merge new versions without losing your edits. - [Registry reference](https://ui.ballmac.com/docs/reference/registry): Addresses, file locations and the JSON format. --- # Build a sales dashboard Add the dashboard block, feed it your data, handle loading and errors, and match your brand. It takes about ten minutes. By the end of this page you have a dashboard that loads your own numbers, shows a skeleton while it waits, and offers a retry when the request fails. You need a project that already has Ballmac UI set up. If you don't, start with [Install your first component](https://ui.ballmac.com/docs/get-started/install). ### Add the block ```bash npx shadcn@latest add @ballmac/dashboard-1 ``` The block goes to `components/ballmac/blocks/dashboard-1/`. The CLI also adds what it builds on, such as the chart, the state view and `recharts`. ### Render it with demo data With no props the block draws a built-in sales curve, so you can see the page before you connect anything. ```tsx title="app/dashboard/page.tsx" import { Dashboard1 } from "@/components/ballmac/blocks/dashboard-1/dashboard-1" export default function Page() { return } ``` You get a date-range switch, four KPI cards with change and trend, a revenue chart against the previous period, revenue by channel and a recent-orders table. Every number is worked out from the series you pass. ### Pass your own numbers `getSeries` returns one row per day for the chosen range. `channels` and `orders` are plain lists. ```tsx title="app/dashboard/page.tsx" import { Dashboard1 } from "@/components/ballmac/blocks/dashboard-1/dashboard-1" const week = [ { label: "Mon", revenue: 8200, previous: 7600, orders: 61 }, { label: "Tue", revenue: 9400, previous: 8100, orders: 70 }, { label: "Wed", revenue: 8800, previous: 8700, orders: 66 }, ] export default function Page() { return ( week} currency="EUR" channels={[{ name: "Web", share: 64 }, { name: "Marketplace", share: 36 }]} orders={[{ id: "ORD-2201", customer: "Fjord Labs", email: "pay@fjord.no", status: "paid", total: 1840, date: "2026-09-30" }]} /> ) } ``` ### Load the data from your API Fetch with `useResource`. It turns a request into the `state` the block takes, aborts a request that is replaced, and retries on demand. ```tsx title="components/sales-overview.tsx" "use client" import * as React from "react" import { Dashboard1, type Dashboard1Range } from "@/components/ballmac/blocks/dashboard-1/dashboard-1" import { useResource } from "@/lib/ballmac/use-resource" export function SalesOverview() { const [range, setRange] = React.useState("7d") const overview = useResource( (signal) => fetch(`/api/overview?range=${range}`, { signal }).then((r) => r.json()), { deps: [range], isEmpty: (o) => o.series.length === 0 } ) return ( overview.data?.series ?? []} channels={overview.data?.channels} orders={overview.data?.orders} /> ) } ``` Changing the range fetches again, and the block shows its skeleton while it waits. `defaultRange={range}` keeps the switch on the range you chose when the block comes back. ### Add a test endpoint If you don't have an API yet, this route returns the same shape the component expects. ```ts title="app/api/overview/route.ts" export function GET(request: Request) { const range = new URL(request.url).searchParams.get("range") ?? "7d" const days = range === "90d" ? 90 : range === "30d" ? 30 : 7 const series = Array.from({ length: days }, (_, i) => ({ label: `Day ${i + 1}`, revenue: 8000 + (i % 7) * 900, previous: 7500 + (i % 5) * 700, orders: 60 + (i % 9) * 4 })) return Response.json({ series, channels: [{ name: "Web", share: 64 }, { name: "Marketplace", share: 36 }], orders: [{ id: "ORD-1", customer: "Fjord Labs", email: "pay@fjord.no", status: "paid", total: 1840, date: "2026-09-30" }], }) } ``` ### See every state Open the block's page and use the **State** switch above the preview to see loading, empty and error, or link straight to one with `/blocks/dashboard-1?state=error`. In your own page, stop the endpoint (or make it return a 500) and the block shows an error with a retry button. Focus is never moved for you, and screen readers hear the loading and error messages. ### Match your brand The chart and the trend lines use your theme's `--chart-1` color, so changing it changes the dashboard. ```css title="app/globals.css" :root { --chart-1: oklch(0.62 0.19 262); } ``` For a whole theme, see [Make it yours](https://ui.ballmac.com/docs/get-started/make-it-yours). ### Check your work Run the quality check on your own page. It reports missing states, unnamed controls, hard-coded colors and layouts that break on a phone. ```bash npx @ballmac/cli check ``` ## Next steps - [Handle loading, empty and error states](https://ui.ballmac.com/docs/guides/states): The `state` prop on every data block and form block. - [Dashboard 1](https://ui.ballmac.com/blocks/dashboard-1): All props, examples and the quality scorecard. - [Update components without losing your edits](https://ui.ballmac.com/docs/guides/update-components): Merge new versions into the copy you changed. - [Connect your AI agent](https://ui.ballmac.com/docs/get-started/connect-your-agent): Let your agent add the next block for you. --- # Connect your AI agent Connect Claude Code, Cursor, VS Code, Windsurf or Codex to Ballmac UI with the @ballmac/mcp server. No account or key needed. By the end of this page your AI assistant can search Ballmac UI, read props and examples, and give you install commands. `@ballmac/mcp` knows the whole catalog, including blocks and multi-page templates, and can plan a page from blocks. It is read-only and needs no account. It needs Node.js 20 or later. ### Add the server to your client Pick your client. ```bash title="Claude Code" claude mcp add ballmac -- npx -y @ballmac/mcp ``` ```json title="Cursor (.cursor/mcp.json), Claude Desktop, Windsurf" { "mcpServers": { "ballmac": { "command": "npx", "args": ["-y", "@ballmac/mcp"] } } } ``` ```json title="VS Code (.vscode/mcp.json)" { "servers": { "ballmac": { "type": "stdio", "command": "npx", "args": ["-y", "@ballmac/mcp"] } } } ``` ```toml title="Codex (~/.codex/config.toml)" [mcp_servers.ballmac] command = "npx" args = ["-y", "@ballmac/mcp"] ``` ### Ask for something Try one of these: - "Show me the Ballmac UI components for AI chat interfaces" - "Add @ballmac/prompt-input and @ballmac/ai-message and build a chat panel with them" - "Which Ballmac UI component should I use for an animated stat, and how do I install it?" - "Build a pricing section using Ballmac UI blocks" - "Is there a Ballmac template for an online store? Install it" ### Ask it to check its work Tell your agent: "before you finish, run `audit_project` and fix every error." The tool reads your source, read-only, and returns findings worst first, each with its fix. The rules are in the [check rules reference](https://ui.ballmac.com/docs/reference/check-rules). ## Next steps - Add the [Ballmac UI skill](https://ui.ballmac.com/docs/guides/agent-skill) so your agent also knows the method: how to pick, install and check. - See every tool, resource and prompt in the [MCP tools reference](https://ui.ballmac.com/docs/reference/mcp-tools). - Give the server your licence key to read Pro items: [Set up Pro](https://ui.ballmac.com/docs/guides/pro#use-pro-with-the-mcp-server). - Prefer the official server? [Use the shadcn MCP server](https://ui.ballmac.com/docs/guides/shadcn-mcp). --- # Make it yours Apply a theme, set your brand color and check dark mode. Ballmac components read the standard shadcn CSS variables, so they take on your brand automatically. By the end of this page your components use your brand color in light and dark. ### Install a theme The [theme builder](https://ui.ballmac.com/themes) has twelve ready-made themes: Graphite, Ocean, Indigo, Violet, Rose, Ember, Amber, Forest, Teal, Sand, Mono and Midnight. Each is a full set of light and dark tokens, with contrast checked for text, focus rings and charts. ```bash npx shadcn@latest add @ballmac/theme-ocean ``` Themes change the variables only. Installing a second theme replaces the first, and your components keep working because they read the same tokens. ### Set your brand color Focus rings, selections and accents come from `--ring` and `--chart-1`. Change them in one place: ```css title="app/globals.css" :root { --ring: oklch(0.62 0.19 262); --chart-1: oklch(0.62 0.19 262); } ``` ### Check dark mode Components read tokens only, so dark mode is whatever your `.dark` class defines. With the Ballmac theme, dark mode is an ink navy rather than pure black. > **Tip:** Want color, typeface, platform feel and motion in one command? Install a [preset](https://ui.ballmac.com/docs/guides/presets). Prefer to tune the theme on a live preview? The [theme builder](https://ui.ballmac.com/themes) changes hue, intensity, radius, density and font, checks contrast, and gives you the result to copy. ## Next steps - See every token a component reads in the [theme tokens reference](https://ui.ballmac.com/docs/reference/theme-tokens). - Get a whole design system, with typeface and platform feel, from a [preset](https://ui.ballmac.com/docs/guides/presets). - Change how a product moves in [Use theme motion in your own code](https://ui.ballmac.com/docs/guides/motion). - Make every component handle like macOS, iOS or Windows with [a platform feel](https://ui.ballmac.com/docs/guides/platform-feels). --- # Update components without losing your edits Install with the ballmac CLI, see what is behind, and merge new versions into your edited copies. `ballmac` sits next to the shadcn CLI. shadcn still writes the files and installs packages. `ballmac` runs it for you and records what landed. Run it in a project that already has a `components.json`. ## Install items with ballmac ```bash npx @ballmac/cli add dialog --with-tests ``` That installs `dialog` and the items it needs, then writes `ballmac.lock.json` and a `.ballmac` folder that holds an untouched copy of each file as it was installed. > **Warning:** Commit both. The untouched copy is what makes merging possible, and your teammates and CI need it too. ## See what is behind ```bash npx @ballmac/cli outdated ``` ```text title="Output" ITEM INSTALLED LATEST YOUR CHANGES WHAT CHANGED badge 1.0.0 1.1.0 none Slightly wider horizontal padding so short labels do not look cramped. button 1.0.0 1.1.0 yes (will be merged) The lg size is taller and larger so it matches the lg input and select. dialog 1.0.0 1.1.0 yes (will be merged) The overlay is a little lighter and uses a standard blur. 3 of 4 behind. Update with: ballmac update (add --dry-run to preview) ``` Every item has a version and a changelog written for someone who customised the file: what behaviour changed, and whether props were added, renamed or removed. Breaking changes are marked. The same notes are on each component page under **What changed**. ## Update, keeping your edits ```bash npx @ballmac/cli update --dry-run npx @ballmac/cli update ``` The first command shows what would happen and changes nothing. For each file, `ballmac` compares three versions: the one you installed, yours now, and the new one. - **You never touched it:** replaced with the new version. - **You edited it, and Ballmac changed other lines:** merged. Both sets of changes are kept. - **You and Ballmac changed the same lines:** the file gets git-style conflict markers, because only you know which one you want. Search for `<<<<<<<`, choose, and run your tests. - **A file you deleted:** stays deleted. New files and new dependencies a version adds are installed and tracked. ```text title="Output" button 1.0.0 → 1.1.0 1.1.0: The lg size is taller and larger so it matches the lg input and select. merged src/components/ballmac/button.tsx your changes kept updated src/components/ballmac/__tests__/button.test.tsx dialog 1.0.0 → 1.1.0 CONFLICT src/components/ballmac/dialog.tsx 1 conflict(s): search for <<<<<<< and choose 2 item(s) updated. 1 file(s) have conflicts to resolve. Originals are in .ballmac/backup/2026-10-11T10-54-02-743Z/ ``` Before anything is written, every file it might change is copied to `.ballmac/backup/` (ignored by git), and if shadcn fails halfway your files are put back. Files that shadcn shares between items, such as your own edits to the i18n helper, are never overwritten. ## See what you changed ```bash npx @ballmac/cli diff button ``` This shows your changes against the version you installed, nothing else. Use it before an update, and to remember why a file differs. ## Fail CI when something is behind `ballmac outdated --exit-code` fails when something is behind, and `--json` prints the same data for scripts. Pro items work the same way: set `BALLMAC_LICENSE_KEY` in your environment or `.env.local` (see [Set up Pro](https://ui.ballmac.com/docs/guides/pro)). Without it only free items are listed. ## Know the limits - Merging is line based and needs `git` on your PATH (it uses `git merge-file`; no repository is needed). Without git, edited files get the `.ballmac-new` treatment described in [Track items you already installed](https://ui.ballmac.com/docs/guides/track-installed-items). - A merge that applies cleanly can still be wrong in meaning. Run the tests, and read the changelog note. - Themes are CSS variables, not files, so they are not merged. Re-apply a theme with the shadcn CLI. - Examples and demos are not tracked, only the items you install. It needs Node.js 20 or later and a project with a `components.json`. The agent side of this is the MCP tools `get_changes` and `get_tests` in the [MCP tools reference](https://ui.ballmac.com/docs/reference/mcp-tools). All commands are in the [CLI reference](https://ui.ballmac.com/docs/reference/cli). Something wrong? [Tell us](https://ui.ballmac.com/support). --- # Track items you already installed Adopt Ballmac items you installed with plain shadcn, so ballmac update can merge new versions into them. Installed with plain `shadcn add`? Adopt the items: ```bash npx @ballmac/cli track npx @ballmac/cli track dialog button ``` The first command tracks every Ballmac item found in the project. The second tracks only the items you name. ## How it records your files A file identical to what shadcn writes today is recorded as untouched. One that differs is recorded **without a base**, because it may be edited or from an older version and there is no way to tell. For those files, an update puts the new version beside your file as `.ballmac-new` instead of guessing. ## Declare a file current Once you have compared the two files, tell `ballmac` your file is current: ```bash npx @ballmac/cli track --rebase button ``` From then on, `ballmac update` merges new versions into it. See [Update components without losing your edits](https://ui.ballmac.com/docs/guides/update-components). --- # Install the tests that ship with components Add the vitest tests Ballmac runs on a component, keep them updated with it, and run them in your project. Most free components come with the test we run on them: keyboard use, states and ARIA, written with vitest and Testing Library. ## Add tests when you install ```bash npx @ballmac/cli add dialog --with-tests ``` ## Add tests for items you already have ```bash npx @ballmac/cli test add button ``` ## Run every Ballmac test ```bash npx @ballmac/cli test ``` ## What gets installed Tests go in `__tests__` next to the components, with one shared `setup.ts`. The tool installs the packages they need at versions known to work together (vitest, jsdom, Testing Library, the React plugin) and, if you have no vitest config yet, creates one with your `@` alias. Pages for components that have a test say so. A test is yours once installed, and it is updated with the component: your additions are merged like any other file. ## Close the loop with an agent After an AI agent edits a component, it can run the test and fix what it broke. The MCP tool `get_tests` returns the test for an item. > **Note:** Pro blocks are tested in batches rather than one by one, so they don't ship per-item tests yet. --- # Check your own app Run ballmac check on your source or your running app, tune it for your project, and gate CI and AI agents on it. `ballmac check` reads your source and reports missing loading and error states, images and buttons without names, hard-coded colors, endless decorative motion and layouts that break on a phone, each with the fix. ## Run it ```bash npx @ballmac/cli check ``` Check one folder, or list every rule: ```bash npx @ballmac/cli check src/app npx @ballmac/cli check --rules ``` It is read-only, needs no account and no network (the rule list is bundled; it only looks up which of your components have states if you are online), and uses the TypeScript version your project already has. Your own `components/ui` and Ballmac files are skipped unless you pass `--include-library`. ```text title="Output" ballmac check · 41 files error a11y/control-name ×1 A button or link has an icon but no accessible name src/app/toolbar.tsx:18:7 }} error={{ title: "Invoices are unavailable", details: String(invoices.error) }} onRetry={invoices.retry} > ``` The props of `StateView` and `useResource` are in the [building blocks reference](https://ui.ballmac.com/docs/reference/building-blocks). ## Related - [Why every block has states](https://ui.ballmac.com/docs/concepts/states) - [Which blocks show states](https://ui.ballmac.com/docs/reference/block-states) --- # Add accessible charts Install a chart, give it your data, and get a table view, patterns for color blindness, a written summary and loading, empty and error states without extra code. Ballmac UI has seven chart components built on [Recharts](https://recharts.org) and the shadcn chart: area, bar, line, pie, radar, radial and scatter. Each one draws inside a **chart frame** that adds what a chart needs to work for everyone. Browse them all, live, on the [charts page](https://ui.ballmac.com/charts). ## Install a chart ```bash npx shadcn@latest add @ballmac/chart-area ``` The command also installs the frame and the base chart, and adds `recharts` to your project. To start from a finished example instead, install it by name, for example `@ballmac/chart-area-stacked`. ## Draw one Pass rows of data, the key that holds each row's category, and the series to draw: ```tsx title="app/page.tsx" import { ChartArea } from "@/components/ballmac/chart-area" const data = [ { month: "Jan", desktop: 4210, mobile: 2480 }, { month: "Feb", desktop: 4860, mobile: 3120 }, { month: "Mar", desktop: 4540, mobile: 3790 }, ] export default function Page() { return ( ) } ``` Colors come from your theme's chart colors in order. Give a series its own with `color: "var(--chart-3)"` or any CSS color. ## Which chart | You want to show | Use | | --- | --- | | A trend, or parts of a whole over time | `chart-area` (stacked, expanded to 100%) | | An exact trend, forecast against actual, lines that cross | `chart-line` (dashed series, labels on the lines) | | A comparison, a ranking, groups | `chart-bar` (columns or flat bars, stacked, sorted) | | A few parts of one whole | `chart-pie` (donut, half ring, total in the middle) | | A goal, or progress rings | `chart-radial` | | A profile across five to eight dimensions | `chart-radar` | | A relationship between two numbers | `chart-scatter` (groups, bubbles) | ## What every chart does for you - **Table view.** A switch above the chart turns it into a table of the same numbers, with a **Download CSV** button. Pass `tableView={false}` to hide the switch. - **Legend.** Each legend item is a button that switches its series off and on. At least one always stays on. Use `legend="static"` for a plain legend or `legend="none"`. - **Patterns.** Add `patterns="toggle"` for a switch that fills series with stripes, dots and hatching as well as color, or `patterns` to always do it. Line charts use dash styles. - **A summary for screen readers.** The chart is a named figure, and its description is written from your data: first to last, highest and lowest, or a ranking. Pass `summary="Mobile caught up in March."` to say what it means instead. - **States.** Pass `state="loading"`, `"empty"` or `"error"` and an `onRetry`. The loading skeleton has the shape of the chart. An empty `data` array shows the empty state by itself. - **Reduced motion.** Chart animations stop for people who ask for less motion. - **Right to left.** Axes reverse and move to the other side when the page reads right to left. ```tsx import { useResource } from "@/lib/ballmac/use-resource" const visits = useResource((signal) => fetch("/api/visits", { signal }).then((r) => r.json())) ``` ## Write numbers your way `valueFormatter` writes a number in the tooltip, the table, the labels and the summary. `categoryFormatter` writes a category, for example a date. The axis has its own formatter, because ticks are usually shorter: ```tsx `$${v.toLocaleString("en-US")}`} axisFormatter={(v) => `$${v / 1000}k`} categoryFormatter={(v) => dateFormat.format(new Date(`${v}T00:00:00Z`))} … /> ``` Axes get round ticks (0, 500, 1K) instead of whatever the data ends on. Fix a scale with `yDomain` (area, line, scatter) or `domain` (bar). ## Use the frame with any Recharts chart For a chart these components do not cover, wrap your own Recharts chart in `ChartFrame` and use what it hands you: ```tsx import { ChartFrame } from "@/components/ballmac/chart-frame" {(chart) => ( {series.map((s) => ( ))} )} ``` `chart.fill(key)` gives a series' fill, which is its pattern when patterns are on. Put `{chart.defs}` inside the chart so the patterns exist. For a chart whose data is not one column per series, pass your own `table={{ columns, rows }}`. ## Dashboards Four blocks put the charts to work: [Charts 1](https://ui.ballmac.com/blocks/charts-1) is an analytics overview, [Charts 2](https://ui.ballmac.com/blocks/charts-2) a revenue report, [Charts 3](https://ui.ballmac.com/blocks/charts-3) small multiples and [Charts 4](https://ui.ballmac.com/blocks/charts-4) a scorecard. Each works out its figures from your data. ## Related - [Handle loading, empty and error states](https://ui.ballmac.com/docs/guides/states) - [Right-to-left layouts](https://ui.ballmac.com/docs/guides/right-to-left) - [Quality, measured](https://ui.ballmac.com/quality) --- # Install a preset Give your app a whole design system with one command: color, shape, typeface, platform feel and motion. Pick one of fifteen, or make your own and share it as a 16-character code. A preset is a design system in one install. It sets your colors (light and dark, contrast checked), corner radius and density, typeface, platform feel and motion together, so they suit each other. A [theme](https://ui.ballmac.com/docs/get-started/make-it-yours) only sets color, corners and motion. A preset adds the typeface and the platform feel, and it has a code. ## Install one Browse the [presets](https://ui.ballmac.com/presets), pick one, and run its command: ```bash npx shadcn@latest add @ballmac/preset-ink ``` The command writes the tokens into your global CSS and, when the preset has an installable typeface, adds the font. Your components keep working because they read the same tokens. Run it again with another name to switch. Presets replace each other. ## Make your own and share the code The [builder](https://ui.ballmac.com/themes) changes every setting on a live preview of real components. The panel shows a **preset code**: ```text 2gf1-6sax-5gj7-5xdq ``` The code is the design: color, shape, typeface, feel and motion packed into 16 characters. Nothing is stored on a server. Anyone can install it: ```bash npx shadcn@latest add @ballmac/preset-2gf1-6sax-5gj7-5xdq ``` Paste a code into **Load a code** in the builder, or open `/themes?code=2gf1-6sax-5gj7-5xdq`, and the design loads so you can keep tuning it. A code that has a typo is rejected, not guessed at. ## Install only some parts [#only] Add `only` to take parts of a preset and keep the rest of your design. The parts are `colors`, `shape`, `font`, `motion` and `feel`. Use the URL form, and quote it: ```bash npx shadcn@latest add "https://ui.ballmac.com/r/preset-ink.json?only=colors,font" ``` The builder's **What to install** boxes write this command for you. The URL form also works with a code. | Part | What it sets | | --- | --- | | `colors` | Light and dark colors, including the five chart colors | | `shape` | Corner radius and density | | `font` | The typeface | | `motion` | Speed, bounce, travel, hover, stagger and the reduced-motion fallback | | `feel` | Control sizes, focus ring, shadows and materials for the platform feel | ## Typefaces [#typefaces] A preset can name one of these open-source variable fonts, or a system font stack that costs nothing to load. The shadcn CLI installs a named font from [Fontsource](https://fontsource.org), so the files are served from your own app and not from a third-party host. On Next.js it uses `next/font`. | Font | Kind | Good for | Install on its own | | --- | --- | --- | --- | | Inter | sans | Neutral, built for screens. The safe default. | `@ballmac/font-inter` | | Geist | sans | Crisp and technical. Developer tools, dashboards. | `@ballmac/font-geist` | | DM Sans | sans | Low contrast, geometric, friendly. | `@ballmac/font-dm-sans` | | Manrope | sans | Modern and a little wide. Fintech, SaaS. | `@ballmac/font-manrope` | | Plus Jakarta Sans | sans | Warm geometric forms. Consumer apps. | `@ballmac/font-jakarta` | | Figtree | sans | Friendly and open. Health, education, community. | `@ballmac/font-figtree` | | Instrument Sans | sans | Slightly condensed, editorial. Studios and brands. | `@ballmac/font-instrument-sans` | | Space Grotesk | sans | Quirky, technical. Crypto, hardware, creative tools. | `@ballmac/font-space-grotesk` | | Bricolage Grotesque | sans | Characterful and bold. Marketing, portfolios. | `@ballmac/font-bricolage` | | Fraunces | serif | A soft, expressive serif. Editorial, food, lifestyle. | `@ballmac/font-fraunces` | | Newsreader | serif | A reading serif. Publications, docs, long text. | `@ballmac/font-newsreader` | | Source Serif 4 | serif | Sturdy and neutral. Finance, legal, research. | `@ballmac/font-source-serif` | | JetBrains Mono | mono | Made for code. Terminals, developer products. | `@ballmac/font-jetbrains-mono` | | Geist Mono | mono | Clean monospace to pair with Geist. | `@ballmac/font-geist-mono` | Install a font without a preset, for example `npx shadcn@latest add @ballmac/font-fraunces`. It sets `--font-sans`. ## How the code works - Each setting is rounded to the step of its slider, then all of them are packed into one number and written in 32 letters and digits that cannot be confused with each other. The last character is a check. - You can type it in any case, with or without dashes. `o` reads as `0`, and `i` and `l` read as `1`. - The format has a version. A code made today keeps meaning the same design, because new fonts are only ever added at the end of the list. - Every value is clamped by the theme engine, so a made-up code can only produce a safe theme. ## Use it from an agent or a script The preset address is plain JSON, so a script can read it: `https://ui.ballmac.com/r/preset-.json`. The [Ballmac skill](https://ui.ballmac.com/docs/guides/agent-skill) tells a coding agent when to use a preset, and the [MCP server](https://ui.ballmac.com/docs/get-started/connect-your-agent) can make one from a description. ## Related - [Make it yours](https://ui.ballmac.com/docs/get-started/make-it-yours) - [Pick a platform feel](https://ui.ballmac.com/docs/guides/platform-feels) - [Use theme motion in your own code](https://ui.ballmac.com/docs/guides/motion) --- # Use Base UI instead of Radix UI Every Ballmac UI component built on Radix UI also comes in a Base UI version with the same props, the same keyboard behavior and the same tests. Install it by URL, or let a Base UI style pick it. Most interactive Ballmac UI components (dialogs, menus, tabs, sliders, tooltips and more) are built on [Radix UI](https://www.radix-ui.com). Each of them also has a version built on [Base UI](https://base-ui.com), the headless library behind shadcn's `base-*` styles. You choose one per project, and you can switch later. Both versions have the same props, the same exports and the same `data-slot` names. Pages and code that use a component keep working when you change which one is installed. ## Which one do you need Check your `components.json`. The `style` says which library your project uses: - A `base-*` style, such as `base-nova`, uses Base UI. - Any other style, such as `radix-nova` or `new-york-v4`, uses Radix UI. If you start a new project with `shadcn init`, you get Base UI unless you ask for Radix. Match the Ballmac version to it, so you ship one headless library, not two. ## Install a Base UI version Every component page with a Base UI version has a **Radix UI | Base UI** switch above the install command. Pick Base UI, and the command becomes: ```bash npx shadcn@latest add https://ui.ballmac.com/r/base/popover.json ``` The command installs the component, the Ballmac items it builds on (their Base UI versions where they have one), and the `@base-ui/react` package. It leaves Radix UI out. `@ballmac/base-popover` is the same file under a name that needs no URL, so `npx shadcn@latest add @ballmac/base-popover` works too. A component with nothing to swap, such as a chart or a card, has one version that works with both. ### Let the style choose The address `https://ui.ballmac.com/r/{style}/popover.json` answers with the version that fits the style. The shadcn CLI replaces `{style}` with your project's style, so pin `@ballmac` to it once: ```bash npx shadcn@latest registry add @ballmac=https://ui.ballmac.com/r/{style}/{name}.json ``` After that, the usual command installs the right version for the project: ```bash npx shadcn@latest add @ballmac/popover ``` A `base-*` style gets the Base UI version, and any other style gets the Radix UI version. If a component has no Base UI version, every style gets the one version it has. ## What stays the same The Base UI versions keep the Radix UI API, so your code does not change. These all work as they do in the Radix UI version: - `onSelect` on menu items, and `preventDefault()` in a close button's `onClick` to keep a dialog open while a request finishes. - `onOpenAutoFocus` and `onCloseAutoFocus` on dialogs, alert dialogs and sheets, to place focus yourself. - `asChild` on Button, Badge, Item and the sidebar menu button. - `value`, `defaultValue` and `onValueChange` on the menubar, and `type` on the scroll area. - Checkbox `"indeterminate"`, toggle group and accordion `type`, and select items written as children. - Right-to-left: the arrow keys follow ``, as before. The same test suite runs against both versions in CI, so a behavior that differs fails the build. ## What differs These are the places where the two libraries behave differently, and what the Base UI version does about it: | | Radix UI | Base UI | | --- | --- | --- | | Styling hooks | `data-state="open"`, `"checked"`, `"active"` | `data-open`, `data-checked`, `data-active`, and `data-popup-open` on a trigger. Ballmac's classes already use them. | | Rendering as your own element | `asChild` | A `render` prop on the part. For example, a menu item that is a link: `render={}`. | | Checkbox, switch and radio | A native button | An element with the right `role`. A disabled one has `aria-disabled` and `data-disabled`, not the `disabled` attribute. Inside a `fieldset disabled`, Ballmac's versions still disable themselves. | | Slider | The thumb is the `slider` | The `slider` is a hidden input inside the thumb. Name it with `aria-label`, `aria-labelledby` or `thumbLabels`. | | Accordion keys | Arrow keys move between headers | Tab moves between headers. | | Focus after a dialog closes | Stays where it was if nothing took it back | Returns to the element that had it. | If you write your own components on top of the Base UI versions, style with the `data-*` attributes above, and use `render` where you would use `asChild` on a part. ## Switch between them Install the other version over the first. Run the `add` command with `--overwrite`: ```bash npx shadcn@latest add https://ui.ballmac.com/r/base/dialog.json --overwrite ``` To go back, add the item by its usual name (`@ballmac/dialog`) with `--overwrite`. Then remove the Base UI package if nothing else uses it. Your own edits to a component are overwritten, so commit first. ## Helpers A Base UI version may add small helper files to your project, in `lib/ballmac`: `positioner` (maps Radix UI's `side`, `align` and `onSelect` onto Base UI), `slot` (`asChild`), `fieldset` (disabled fieldsets), `menubar-value` and `direction`. They are small, and a component pulls in the ones it needs when you add it. --- # Use theme motion in your own code Make your own CSS and JavaScript animations follow the theme's speed, bounce, travel, hover and stagger, and share a motion setup as a link. ## Follow the theme in CSS Use the `--bm-*` variables the theme defines: ```css title="Your CSS" .card { transition: transform var(--bm-duration-base) var(--bm-ease-out); } .card:hover { transform: translateY(var(--bm-lift)); /* -2px at hover 1, 0 at hover 0 */ } .card:active { transform: scale(var(--bm-press)); /* 0.97 at hover 1 */ } .toast { transform: translateY(var(--bm-distance)); /* enter distance, 10px at travel 1 */ transition: transform var(--bm-duration-slow) var(--bm-ease-spring); } .list > * { transition-delay: calc(var(--i) * var(--bm-stagger-step)); } .glow { animation: pulse 2s infinite; animation-play-state: var(--bm-ambient-state); /* running or paused */ } ``` Tailwind's own classes follow too, with no edits: `duration-*`, `delay-*`, `ease-out`, `ease-in`, `ease-in-out` and `ease-spring`. ## Follow the theme in JavaScript `@ballmac/motion-presets` reads the same variables. Import the constants for one-off values, or call `useMotion()` when a component should follow the theme live. ```tsx title="components/toast.tsx" import { motion } from "motion/react" import { useLoopsPaused, useMotion } from "@/lib/ballmac/motion" export function Toast({ children }: { children: React.ReactNode }) { const m = useMotion() return ( {children} ) } ``` ## Hold decorative loops still Decorative loops hold still when the theme turns them off, or under reduced motion. Use `useLoopsPaused` for those only: ```tsx function Glow() { const still = useLoopsPaused() return } ``` > **Note:** Spinners and "thinking" indicators carry meaning, so they should keep running. Don't pause them with `useLoopsPaused`. ## Share a motion setup as a link A feel has a short address, and any combination is a link. Nothing is stored, and every value is clamped to its range, so a link can never produce an unsafe theme. ```bash # a ready-made feel https://ui.ballmac.com/themes?mo=playful # or any values: speed, bounce, travel, hover, stagger, ambient (1 or 0), reduce (system or always) https://ui.ballmac.com/themes?sp=1.3&bn=0.6&tv=0.8&hv=1.2&st=0.5&am=0 ``` Install a custom design, color and motion together: ```bash npx shadcn@latest add "https://ui.ballmac.com/themes/custom.json?h=262&mo=calm" ``` --- # Pick a platform feel Make every component handle like macOS, iOS or Windows, by installing one feel or letting the device choose before the first paint. ## Install one feel For an app that always runs on one platform, install its feel. It changes handling only and leaves your colors alone. ```bash npx shadcn@latest add @ballmac/feel-macos ``` The other feels are `@ballmac/feel-ios`, `@ballmac/feel-windows` and `@ballmac/feel-web`. See [what each feel sets](https://ui.ballmac.com/docs/reference/platform-feels). ## Let the device pick A Tauri or Electron app that ships to Mac and Windows, or a web app used on phones and desktops, should handle like the platform it is on. `feel-auto` includes all four feels and sets the right one before the first paint, so there is no flash. ```bash npx shadcn@latest add @ballmac/feel-auto ``` Add `FeelScript` to your root layout: ```tsx title="app/layout.tsx" import { FeelScript } from "@/components/ballmac/feel-script" export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` ## Let people override it Go back to the device's own feel with `auto`. The choice is remembered in the browser. ```tsx import { useFeel } from "@/lib/ballmac/feel" const { feel, setFeel } = useFeel() setFeel("windows") // "web" | "macos" | "ios" | "windows" setFeel("auto") // the device's own feel ``` ## Share a feel as a link ```bash # open a feel in the builder https://ui.ballmac.com/themes?fe=windows ``` Install a custom design with a feel, colors and motion together: ```bash npx shadcn@latest add "https://ui.ballmac.com/themes/custom.json?h=262&fe=macos" ``` ## Related - [How platform feels work](https://ui.ballmac.com/docs/concepts/platform-feels) - [Ship a desktop app](https://ui.ballmac.com/docs/guides/desktop-app) --- # Ship a desktop app Draw your own window chrome in a Tauri v2 or Electron app with app-window, wired to the real window actions. `app-window` is the window chrome of a real app: a title bar that drags the window, maximizes on double-click, and carries the controls the platform draws. It has no Tauri or Electron dependency. You pass the actions in. ```bash npx shadcn@latest add @ballmac/app-window @ballmac/feel-auto ``` ## Use it in Tauri v2 ### Turn off the native frame ```json title="src-tauri/tauri.conf.json" { "app": { "windows": [{ "title": "Notes", "decorations": false }] } } ``` ### Allow the window actions ```json title="src-tauri/capabilities/default.json" { "identifier": "default", "windows": ["main"], "permissions": [ "core:default", "core:window:allow-close", "core:window:allow-minimize", "core:window:allow-toggle-maximize", "core:window:allow-is-maximized", "core:window:allow-set-fullscreen", "core:window:allow-start-dragging" ] } ``` ### Wire the buttons ```tsx title="src/App.tsx" import { getCurrentWindow } from "@tauri-apps/api/window" import { AppWindow, AppWindowContent, AppWindowTitleBar } from "@/components/ballmac/app-window" const win = getCurrentWindow() export default function App() { const [maximized, setMaximized] = useState(false) useEffect(() => { win.isMaximized().then(setMaximized) const unlisten = win.onResized(() => win.isMaximized().then(setMaximized)) return () => void unlisten.then((f) => f()) }, []) return ( win.close()} onMinimize={() => win.minimize()} onMaximize={() => win.toggleMaximize()} onFullscreen={async () => win.setFullscreen(!(await win.isFullscreen()))} > … ) } ``` ## Use it in Electron Create the window without a frame and handle the actions in the main process: ```ts title="main.ts" const win = new BrowserWindow({ frame: false, webPreferences: { preload: join(__dirname, "preload.js") } }) ipcMain.on("window", (event, action: "close" | "minimize" | "maximize") => { const w = BrowserWindow.fromWebContents(event.sender) if (!w) return if (action === "maximize") w.isMaximized() ? w.unmaximize() : w.maximize() else w[action]() }) ``` Expose a small bridge in the preload script: ```ts title="preload.ts" contextBridge.exposeInMainWorld("windowControls", { send: (action: "close" | "minimize" | "maximize") => ipcRenderer.send("window", action), }) ``` Pass the actions to the window in the renderer: ```tsx title="renderer" window.windowControls.send("close")} onMinimize={() => window.windowControls.send("minimize")} onMaximize={() => window.windowControls.send("maximize")} /> ``` The title bar sets both `data-tauri-drag-region` and `-webkit-app-region: drag`, and the toolbar inside it is marked no-drag, so buttons stay clickable. > **Note:** Windows 11's snap layouts and the macOS window-tiling menu belong to native controls. See [the limits of platform feels](https://ui.ballmac.com/docs/concepts/platform-feels#know-the-limits). ## Start from the desktop blocks The free [desktop blocks](https://ui.ballmac.com/blocks) (preferences, menu bar and tray, software update, licence activation, permissions setup, About, welcome window and shortcuts editor) draw real window chrome with `app-window` and handle like macOS or Windows from the page's feel. The AI notes on the software update block show how to wire `tauri-plugin-updater` and `electron-updater`. --- # Turn on right-to-left Set the page direction and every component, block and template mirrors. Add the direction provider, write RTL-safe code and test it. ## Set the direction Set `dir` and `lang` on ``, and wrap the app in `DirectionProvider` so the Radix-based components (tabs, sliders, menus, radio groups) know the direction too. ```bash npx shadcn@latest add @ballmac/direction ``` ```tsx title="app/layout.tsx" import { DirectionProvider } from "@/lib/ballmac/direction" export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` Items that need the direction in code (`Tabs`, `Slider`, `Calendar`, `Carousel`, `Sidebar` and others) add it for you. They also read `` on their own, so an app that sets only the attribute still works. The provider adds the Radix side. Give a region its own direction with ``. ## Test it Every component and block preview has a right-to-left toggle in its toolbar. Any preview opens right-to-left with `/preview/?dir=rtl`. `pnpm rtl:sweep` loads every preview in both directions and reports any whose layout isn't the mirror image of the other, or that overflows only in RTL. ## Write RTL-safe code The repository checks this on every build (`pnpm check` runs `scripts/rtl.ts`): - Physical classes are rejected: `ml-` `mr-` `pl-` `pr-` become `ms-` `me-` `ps-` `pe-`; `left-` and `right-` become `start-` and `end-`; `text-left` becomes `text-start`; `border-l` becomes `border-s`; `rounded-l` becomes `rounded-s`. Centering with `left-1/2 -translate-x-1/2` is symmetric and allowed. - Directional icons from lucide-react must have an `rtl:` class. `npx tsx scripts/rtl.ts --fix` rewrites the safe cases. - Anything that is physical on purpose carries a comment containing `rtl-fixed` and a reason, or is listed in `scripts/rtl-exceptions.json`. - A `translate-x` nudge needs its mirror: `group-hover:translate-x-1 rtl:group-hover:-translate-x-1`. ## Know the limits - Templates mirror, but their sample copy is English and written into the files, so translate it as you would any content. - Recharts draws SVG in its own coordinates: axes don't mirror. Pass `reversed` to an axis yourself if your design needs it. - The marquee and blur-fade `direction` props are physical. Choose the value you want for your reading direction. ## Related - [What mirrors, and what doesn't](https://ui.ballmac.com/docs/concepts/right-to-left) - [Translate Ballmac UI](https://ui.ballmac.com/docs/guides/translate) --- # Translate Ballmac UI Translate every built-in label, placeholder and screen reader text with one provider, and set the locale for dates and numbers. Every built-in label, placeholder and screen reader text is a message with an English default. One provider translates all of them and sets the locale for dates and numbers. The full list is in the [messages reference](https://ui.ballmac.com/docs/reference/messages). ## Add the provider ```bash npx shadcn@latest add @ballmac/i18n ``` ```tsx title="app/layout.tsx" import { I18nProvider } from "@/lib/ballmac/i18n" import ar from "@/messages/ar.json" export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` `messages` is a flat object from key to text. Anything you leave out stays in English, so you can translate in stages. ## Start from the full key list Download the complete list of keys with their English text from [/i18n/en.json](https://ui.ballmac.com/i18n/en.json), copy it to `ar.json`, and translate the values. ## Use placeholders and plurals ```json title="messages/ar.json" { "pagination.nextPage": "الصفحة التالية", "data-table.pageOf": "الصفحة {page} من {total}", "workspace-card.members_one": "عضو واحد", "workspace-card.members_two": "عضوان", "workspace-card.members_few": "{count} أعضاء", "workspace-card.members_many": "{count} عضوًا", "workspace-card.members_other": "{count} عضو" } ``` `{name}` is replaced with a value. Where a message depends on a number, add one key per plural category your language has (`_zero`, `_one`, `_two`, `_few`, `_many`, `_other`, chosen with `Intl.PluralRules`). English needs only `_one` and `_other`, which are built in. ## Set the locale for dates, numbers and money The provider's `locale` is used by every component that formats a number, a date, a currency or a duration. Without a provider, `` is used, then `en-US`. A `locale` prop on a single component always wins. To get Western digits in an Arabic UI, use `ar-u-nu-latn`. ## Translate your own components ```tsx "use client" import { useLocale, useMessages } from "@/lib/ballmac/i18n" export function Greeting({ name }: { name: string }) { const msg = useMessages() return

{msg("app.greeting", "Welcome back, {name}", { name })}

} ``` `msg.rich` fills placeholders with React nodes, for example a ``. If you already use next-intl, i18next or Lingui, keep them for your app and pass their output to `I18nProvider` as `messages`. ## What is translated, and what is not - All components: accessible names, placeholders, hidden text, default button and empty-state text, status words and templated sentences. - Props still win. `closeLabel`, `emptyMessage`, `label` and similar props override the dictionary. - Blocks and templates are copy-in starting points. Their headlines and sample copy are props or live in the file, so you edit them as content. The right-to-left layout is covered in [What mirrors in right-to-left](https://ui.ballmac.com/docs/concepts/right-to-left). - Sample values (such as the `.env` placeholder) and brand names aren't messages. --- # Use your own images Every hero, feature, card and template ships with generated artwork. Pass an image and it replaces the artwork, with the shape, loading and alt text handled. ## Pass one prop ```tsx title="app/page.tsx" import { Hero1 } from "@/components/ballmac/blocks/hero-1" ``` The prop is called `media` on blocks with one big picture, and `image` on items in a list (a post, a speaker, a project). It accepts a URL, an object with the alt text, or your own element such as a `next/image` or a video. ```tsx // URL plus alt // full control } /> // your own element ``` ## What you get - **Alt text is required.** In development a missing `alt` logs a warning. Use `alt=""` only for decoration. - **No layout jump.** Each slot reserves a fixed aspect ratio before the file arrives. - **Lazy by default.** Slots above the fold (hero) load right away with high priority. - **Dark mode.** `srcDark` swaps the file when an ancestor has the `dark` class. - **Never broken.** If the file is missing or fails to load, the built-in artwork shows instead of a broken icon. - **Right-to-left safe.** Nothing here depends on reading direction. ## Use the Media component directly Everything above is one component, `Media`, which you can use in your own layouts. ```bash npx shadcn@latest add @ballmac/media ``` ```tsx import { Media } from "@/components/ballmac/media" ``` `aspect` takes `square`, `video`, `photo`, `wide`, `portrait`, `cinema` or a ratio like `"3/2"`. `fit` is `cover`, `contain` or `fill`. All props are in the [building blocks reference](https://ui.ballmac.com/docs/reference/building-blocks). ## Where it works Hero, feature and newsletter blocks, login and download screens, blog and changelog cards, the team grid, the device frames (phone, tablet, laptop, browser, watch, Android), the lock screen, control center, bento grid and team switcher, and the portfolio, studio, publication, podcast and goods templates. Each block page lists its image props. --- # Use the shadcn MCP server Ballmac UI is a standard shadcn registry, so the official shadcn MCP server works once the registry is in your project. ## Add the registry to your project The `shadcn` CLI knows `@ballmac` from the official registry directory, but the MCP server only reads the registries listed in `components.json`, so add it there: ```bash npx shadcn@latest registry add @ballmac=https://ui.ballmac.com/r/{name}.json ``` ## Connect your client ```bash npx shadcn@latest mcp init --client claude ``` Use `--client cursor`, `--client vscode`, `--client codex` or `--client opencode` for the others. For Windsurf and other clients, add the server to your client's MCP configuration: ```json { "mcpServers": { "shadcn": { "command": "npx", "args": ["shadcn@latest", "mcp"] } } } ``` ## What the agent sees The shadcn MCP server exposes tools to list, search and view registry items, fetch examples, and get the add command. Each Ballmac item includes what an agent needs to pick it and wire it up. See [Built for AI agents](https://ui.ballmac.com/docs/concepts/built-for-agents). > **Tip:** The [Ballmac MCP server](https://ui.ballmac.com/docs/get-started/connect-your-agent) adds tools the shadcn one doesn't have, such as page planning, change notes, tests and the quality audit. --- # Use Ballmac with the shadcn chat kit Trace, Questionnaire and Code Block have the same parts and props as shadcn's, so agent output drops into a chat built with either library. shadcn's chat kit has three parts that an AI interface shows in almost every turn: a **Trace** for what the agent did, a **Questionnaire** for questions it needs answered, and a **Code Block** for what it ran or wrote. Ballmac has all three with the same part names and props, so code written for one works with the other. ## Install ```bash npx shadcn@latest add @ballmac/trace @ballmac/questionnaire @ballmac/code-block ``` `questionnaire` is built on shadcn's headless `@shadcn/react/questionnaire`, which is installed with it, so its keyboard, form and validation behavior is the same as theirs. `trace` and `code-block` are our own code with the same API. ## One agent turn ```tsx Ran the billing tests 2 failed {output} ``` The [Trace page](https://ui.ballmac.com/components/trace) has this turn live, with a questionnaire under it. ## What is the same | Part | Same as shadcn | Also in Ballmac | | --- | --- | --- | | Trace | `TraceLine` with `status`, `TraceIcon`, `TraceTitle`, `TraceDescription`, `TraceCollapsible`, its trigger and content | A running title shimmers, the content respects reduced motion, and the open state is a controlled prop | | Questionnaire | Every part, `items`, `shortcuts`, `multiple`, `invalid`, controlled `item` | Button labels come from the [translations](https://ui.ballmac.com/docs/guides/translate), and the actions use our `Button` | | Code Block | `CodeBlockHeader`, `Title`, `Actions`, `CopyButton`, `Content`, `Line`, `Footer`, `size`, `variant`, `lineNumbers`, `startLine`, `wrap` | `useHighlightedCode` highlights with no async loading, and the ready-made panel (`code`, `filename`, `language`) still works | ## Where it differs - `useHighlightedCode` uses Ballmac's small built-in tokenizer (JSON, shell, JavaScript and TypeScript, Python, Go, HTTP and `.env`), not Shiki, so there is nothing to load and it renders on the server. For other languages, render your own highlighted lines inside `CodeBlockLine`, or use Shiki output as children of the ready-made panel. - ANSI colors in terminal output are not rendered. Strip the escape codes before you pass the text in. - `CodeBlock` with no parts inside is the ready-made panel; with `CodeBlockHeader`, `CodeBlockActions`, `CodeBlockContent` or `CodeBlockFooter` as direct children it is the compound block. Wrapping the parts in another component switches it back to the panel, so keep them direct. ## Related - [Built for AI agents](https://ui.ballmac.com/docs/concepts/built-for-agents) - [States](https://ui.ballmac.com/docs/guides/states) --- # Set up Ballmac UI Pro Add your licence key and the private registry once per project, then install Pro blocks and starter apps with the shadcn CLI or the MCP server. Pro items install the same way as free ones, from a private registry that checks your licence key. Set it up once per project. ## Get a licence key Buy Pro on the [pricing page](https://ui.ballmac.com/pricing). Your licence key arrives by email from our payment partner. Keep it private: anyone with the key can install Pro items. > **Tip:** You don't need the command line to use Pro. [Log in with your licence key](https://ui.ballmac.com/pro/login) to read and copy the code of any Pro block on its page, download the starter apps as a zip, and get install commands with your key already filled in. There is no password and no account: the key is the login, and it is kept in an encrypted cookie in your browser until you log out. ## Add the key to your project Put it in `.env.local`, which the shadcn CLI reads. Don't commit this file. ```bash title=".env.local" BALLMAC_LICENSE_KEY=your-licence-key ``` ## Add the Pro registry Add both registries to `components.json`. The CLI sends your key only to the Pro registry. ```json title="components.json" { "registries": { "@ballmac": "https://ui.ballmac.com/r/{name}.json", "@ballmac-pro": { "url": "https://ui.ballmac.com/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${BALLMAC_LICENSE_KEY}" } } } } ``` ## Install Pro items Pro items use the `@ballmac-pro` namespace. Their page shows the exact command. ```bash npx shadcn@latest add @ballmac-pro/ ``` Free items keep working as before, and a Pro item can depend on free ones. ## Download a starter app A starter is a complete app you download and own. **Beacon SaaS** is a Next.js app with sign-in, workspaces with teams and invitations, Stripe billing, a dashboard, settings and API keys. Download it with the same key: ```bash mkdir my-app && curl -fsSL -H "Authorization: Bearer $BALLMAC_LICENSE_KEY" https://ui.ballmac.com/r/pro/starters/beacon-saas.tar.gz | tar -xz -C my-app --strip-components=1 && cd my-app && pnpm install && pnpm dev ``` It runs on an embedded database in development, so there is nothing else to install. The README in the download covers customising it, billing and deployment. **Cove** (`cove-desktop`) is a Tauri 2 desktop app, a notes app that looks native on macOS and Windows: traffic lights or caption buttons, the system blur behind the sidebar on a Mac, native menus and a command palette. It runs in a browser too, so you can build the interface without installing Rust. ## Import the Figma design tokens Every Ballmac theme as W3C design tokens, with light and dark as separate groups (one Figma variable mode each) and the original color kept beside each hex value. Import them with a Figma plugin that reads the W3C token format, such as Tokens Studio. ```bash curl -fsSL -H "Authorization: Bearer $BALLMAC_LICENSE_KEY" https://ui.ballmac.com/r/pro/kits/ballmac-figma-tokens.tar.gz | tar -xz ``` ## Use Pro with the MCP server Give the Ballmac MCP server your key and it can read Pro items and give your agent the right install commands. ```bash title="Claude Code" claude mcp add ballmac --env BALLMAC_LICENSE_KEY=your-licence-key -- npx -y @ballmac/mcp ``` In a JSON config, add `"env": { "BALLMAC_LICENSE_KEY": "your-licence-key" }` next to `args`. Your [Pro library](https://ui.ballmac.com/pro) shows these commands with your own key filled in. ## Use Pro in CI and with a team Set `BALLMAC_LICENSE_KEY` as a secret in your CI or hosting provider. Each person on a Team licence can use the shared key in their own `.env.local`. ## Check a key ```bash curl -s -X POST https://ui.ballmac.com/api/v1/license/verify -H "content-type: application/json" -d '{"key":"your-licence-key"}' ``` The answer is `{"valid":true}` or a reason the key isn't accepted. ## Troubleshoot - **I logged in but the code doesn't show:** reload the page. If you still see the lock, your session ended (for example after you revoked the key); [log in again](https://ui.ballmac.com/pro/login). - **401 licence required:** the CLI didn't send a key. Check that `BALLMAC_LICENSE_KEY` is in `.env.local` and that the `@ballmac-pro` entry has the `headers` block. - **403 licence invalid:** the key was mistyped or is no longer active. Copy it again from your purchase email. - **Unknown registry @ballmac-pro:** the `registries` block is missing from `components.json`. Still stuck? [Contact support](https://ui.ballmac.com/support?topic=help) and include the item name and the error you see. Never send your licence key: we find your purchase from your email. ## Licence terms What you may do with Pro items is set out in the [Pro licence agreement](https://ui.ballmac.com/license/pro). In short: build as many apps and sites as you like, for yourself or your clients, but don't share, resell or publish the Pro source or your key. --- # CLI commands Every ballmac command and option, generated from the CLI's own help text. Run `ballmac` through `npx @ballmac/cli`. This page lists every command and option the tool prints in `ballmac --help`. ```bash npx @ballmac/cli [options] ``` ## `ballmac add ` [#add] Install items with shadcn and start tracking them | Option | What it does | | --- | --- | | `--with-tests` | also install the tests that ship with the items | | `--no-install` | do not install the test packages (print them instead) | ## `ballmac outdated [item…]` [#outdated] Which tracked items have a newer version, and what changed | Option | What it does | | --- | --- | | `--json` | machine-readable output | | `--exit-code` | exit 1 when something is behind (for CI) | ## `ballmac update [item…]` [#update] Merge new versions into your copies (your edits are kept) | Option | What it does | | --- | --- | | `--dry-run` | show what would change and write nothing | ## `ballmac diff ` [#diff] What you changed since you installed an item ## `ballmac track [item…]` [#track] Start tracking items you installed with plain shadcn | Option | What it does | | --- | --- | | `--rebase` | declare your files up to date with the latest version | ## `ballmac check [path…]` [#check] Audit your app for what agents and people get wrong: missing states, unlabelled controls, fixed colours, endless motion, overflow on phones | Option | What it does | | --- | --- | | `--rules` | list the rules and exit | | `--format ` | pretty (default), json or github (annotations for CI) | | `--fail-on ` | error (default), warn or never: when to exit with 1 | | `--all` | show every finding, not the first few per rule | | `--offline` | do not read the Ballmac catalogue | | `--include-library` | also audit components/ui and components/ballmac | | `--url
` | also load a running app in a real browser (axe, overflow, console) | | `--routes ` | routes to load with --url (default /) | ## `ballmac verify ` [#verify] Score any shadcn registry (a URL, a folder or a registry.json) on what can be checked from its source, and write a badge. Needs TypeScript in this project. | Option | What it does | | --- | --- | | `--min-score ` | exit 1 when the score is below n (for CI) | | `--format ` | pretty (default) or json | | `--out ` | write the scorecard JSON | | `--badge ` | write the "Ballmac Verified" SVG badge | | `--item-url ` | where items live when it is not next to registry.json, e.g. https://acme.com/r/\{name\}.json | | `--limit ` | score only the first n items | | `--all` | list every item that lost points | ## `ballmac test [item…]` [#test] Run the Ballmac tests installed in this project ## `ballmac test add ` [#test-add] Install the tests for items that are already installed ## Global options [#global-options] | Option | What it does | | --- | --- | | `--cwd ` | Project folder (default: the current folder) | | `-v, --version` | Print the version | | `-h, --help` | Print this help | ## Environment variables [#environment] | Variable | What it does | | --- | --- | | `BALLMAC_UI_URL` | Registry to read (default https://ui.ballmac.com) | | `BALLMAC_LICENSE_KEY` | Your Ballmac UI Pro key (env or .env.local); needed for Pro items | | `BALLMAC_SHADCN` | How to run shadcn, e.g. "pnpm dlx shadcn@latest" (default: your local copy, else the package manager's runner) | ## Related - [Update components without losing your edits](https://ui.ballmac.com/docs/guides/update-components) - [Check your own app](https://ui.ballmac.com/docs/guides/check-your-app) --- # Check rules Every rule ballmac check and the audit_project tool apply, with why it matters, how to fix it and an example. 15 rules. Each one says why it matters to the person using your app and how to fix it. To run them, see [Check your own app](https://ui.ballmac.com/docs/guides/check-your-app). To change a rule's level, set it in `.ballmacrc.json`. ## States [#states] ### states/ballmac-state-prop [#states-ballmac-state-prop] **Warning.** A Ballmac component with states is used without a state prop The component can show a loading skeleton, an empty message and an error with a retry, but this use only ever shows the ready view. When the request is slow or fails, people see a blank area or a frozen screen. **Fix:** Pass `state` from your data hook, for example state=\{isPending ? "loading" : isError ? "error" : rows.length ? "ready" : "empty"\} and onRetry=\{refetch\}. Instead of: ```tsx ``` Write: ```tsx ``` ### states/data-without-states [#states-data-without-states] **Warning.** A component fetches data but never reads loading or error state While the request is running, or if it fails, the screen has nothing to show. That is the first thing a person sees on a slow connection. **Fix:** Read the loading and error values the hook returns (isPending, isError, error), render a skeleton for loading and a message with a retry for errors, and an empty state when there is no data. Instead of: ```tsx const { data } = useQuery(...) return ``` Write: ```tsx const { data, isPending, isError, refetch } = useQuery(...) if (isPending) return if (isError) return return ``` ## Accessibility [#a11y] ### a11y/img-alt [#a11y-img-alt] **Error.** An image has no alt attribute Screen reader users hear the file name or nothing. Search engines and failed loads show nothing useful either. **Fix:** Add alt with a short description of what the image shows, or alt="" if it is purely decorative. Instead of: ```tsx ``` Write: ```tsx The dashboard with a revenue chart ``` ### a11y/control-name [#a11y-control-name] **Error.** A button or link has an icon but no accessible name Screen reader users hear only “button” with no hint of what it does, and voice control users cannot say its name. **Fix:** Add aria-label="What it does" to the control, or include visually hidden text such as \Close\. Instead of: ```tsx ``` Write: ```tsx ``` ### a11y/clickable-non-interactive [#a11y-clickable-non-interactive] **Error.** A click handler is on an element that keyboards cannot reach A \
with onClick cannot be focused or activated with the keyboard, and screen readers do not announce it as something to press. **Fix:** Use a \ ``` ### a11y/focus-outline-removed [#a11y-focus-outline-removed] **Error.** The focus outline is removed and nothing replaces it Keyboard users lose track of where they are. It is one of the most common ways an app becomes unusable without a mouse. **Fix:** Keep the default outline, or replace it with a visible style such as focus-visible:ring-2 focus-visible:ring-ring. Instead of: ```tsx