Ballmac UI home
Get Pro

Contribute

Build the next item with us

The free library is open source. Bring a component, a block or a fix. If it meets the standard it ships, with your name in the changelog.

Propose an item View on GitHub

The path

From idea to merged in four steps

  1. Propose it

    Open the short proposal form: the name, who needs it, and what the best existing version does that yours does better. We answer before you write much code.

    Open the form

  2. Build it to the standard

    Every item has every state, full keyboard support, reduced motion, tokens only and a demo worth installing. The list is below, and AUTHORING.md has the detail.

    Read AUTHORING.md

  3. Run the checks

    One command line runs the registry build, licence and dependency checks, tests, lint and types. A pull request that passes them is easy to review.

    See CONTRIBUTING.md

  4. Open a pull request

    Target the preprod branch, add screenshots in light and dark, and keep to one item. We review, you answer, we merge, and your item is in the next release with a changelog line.

    Start a pull request
Before you open the pull request
pnpm install
pnpm build:registry
pnpm check && pnpm lint && pnpm typecheck && pnpm test
pnpm a11y <name>      # for the items you touched

The standard

What every item has

This is what keeps one library feeling like one library. It is also how we compare with every other library: the best existing version, then better.

  • Every state

    Default, hover, focus, active, disabled, loading or empty, invalid, in light and dark.

  • Keyboard and ARIA

    Radix for anything with focus management. Every control reachable, with a visible focus ring.

  • Reduced motion

    Motion only through the shared presets, and it stops for people who ask for less.

  • Tokens only

    Theme variables, never hex values, so it follows any theme and any platform feel.

  • Typed and documented

    A props type with a comment on every prop. The site's API table is written from it.

  • Right to left, translated

    Logical properties, mirrored arrows, and every built-in string through the message helper.

  • Tested

    A test for anything interactive: keyboard, controlled and uncontrolled use.

  • Clean licence

    Your own code, or MIT, ISC, BSD or Apache-2.0 code with a credit line. Never paid or unlicensed sources.

Where help is wanted

Good places to start

We are not chasing a bigger count. We want items nobody else has, done properly.

Vertical app blocks
Screens for one trade: a clinic schedule, a restaurant order board, a matter list for a law firm, a property listing with a map.
Ops and admin
Audit log, access review, on-call rota, queue depth and retry screens, with the loading, empty and error states done.
Data entry
Forms people fill in all day: a bill of materials, a timesheet grid, a bulk editor with undo.
Fixes and polish
A bug you hit, an accessibility gap, a clearer demo, a better translation of a message. Small pull requests are welcome without a proposal.

Licence and credit

What happens to your code

  • A merged contribution is licensed under the repository's MIT licence, as in CONTRIBUTING.md. You keep your copyright.
  • The free library only. Ballmac UI Pro is written by Ballmac and does not take outside code.
  • Code from another project needs a permissive licence (MIT, ISC, BSD or Apache-2.0), a “Based on” line and its source in the item's metadata. We check this in CI.
  • You are named in the changelog entry for your item.

Already built something with Ballmac UI?

Show it in the gallery, with the items it uses. It takes one short form.

Add your project