Open-code UI components for Vue and React — installed as source you own, built for humans and agents.
Documentation · Component library · Design systems · Changelog
npx balsa-ui@latest add buttonThat's it. Balsa detects whether your project is Vue or React, installs the matching implementation as editable source in your repository, and never asks you to import from a black box.
You own the code. Components install as readable source into your project, not as a dependency you import. Edit them. Balsa tracks what it installed and, on update, preserves anything you changed rather than overwriting it.
One catalog, more than one framework. The same component exists for Vue and React, built
on a shared framework-neutral core, so a design decision lands in both. balsa add button is
the correct command in either project — the CLI resolves the framework and reports an error
rather than guessing when a project is ambiguous.
Built to be read by agents. Every component ships a machine-readable specification whose props, types, and enumerated values are derived from the source by the compiler, not written by hand. An agent can search by intent, read one specification, and install the right component without scraping documentation.
Design systems, not just components. Palettes, design themes, and gradient backgrounds are independent layers that work alone or together, so the catalog adapts to your product instead of imposing one look.
| Items | Primitives | Compositions | |
|---|---|---|---|
| Vue 3 | 102 | 71 | 39 |
| React 19 | 99 | 71 | 39 |
Every Vue UI component has a React implementation. Shared CSS, the theme core, and the portal core are consumed by both.
npx balsa-ui@latest init # create components.json, install peer deps
npx balsa-ui@latest search "settings form"
npx balsa-ui@latest info input --markdown
npx balsa-ui@latest add input button modalinit writes a shadcn-compatible components.json only when one is missing, and both init
and add install required npm packages through your detected npm, pnpm, Yarn, or Bun — while
preserving existing configuration and source.
<script setup lang="ts">
import { Plus } from "@lucide/vue";
import Button from "@/components/ui/Button.vue";
</script>
<template>
<Button :prefix-icon="Plus">Create project</Button>
</template>import { Plus } from "lucide-react";
import Button from "@/components/ui/Button";
<Button prefixIcon={Plus}>Create project</Button>;Balsa is designed so an agent can work from intent rather than from prose:
npx balsa-ui@latest search "settings form" # intent → candidate items
npx balsa-ui@latest info input --markdown # one item's derived contract
npx balsa-ui@latest add input # install it
npx balsa-ui@latest mcp --tools # same answers over MCP/stdioRead only the selected .balsa/specs/components/<name>.json; the compact catalog index is a
fallback for when CLI search is unavailable. The CLI keeps catalogs, specifications, provenance,
and the optional Balsa agent skill synchronized inside your project.
Hosted machine-readable surfaces:
https://balsa-ui.com/llms.txt·llms-full.txtcatalog-index.jsonspecs/components/button.jsondocs/components/button.md- Registry payloads:
/r/<name>.json(Vue) ·/r/react/<name>.json(React)
Eight authored design systems install by name, and three design themes restyle the whole catalog without touching component source:
npx balsa-ui@latest design-system apply press
npx balsa-ui@latest theme apply --list # modern-flat, brutalism, glassmorphism
npx balsa-ui@latest palette create product --config PAYLOAD
npx balsa-ui@latest background create hero --preset obsidian-foldEvery item is measured against the Balsa design system contract — theme tokens rather than raw values, a stable identity attribute, and documented theme resolution — and the result is computed from source rather than declared by the author:
| Fully integrated | Partial | |
|---|---|---|
| Vue | 91 | 6 |
| React | 92 | 5 |
Component contracts are derived by the TypeScript compiler and vue-component-meta, so
balsa info reports types and enumerated unions that are true by construction. The release
gate proves all of them against their sources on every change.
balsa init balsa add <item...> balsa list
balsa search "<intent>" balsa info <item> balsa docs <item>
balsa view @shadcn/stepper balsa diff balsa update
balsa doctor balsa mcp --tools balsa version
balsa theme apply balsa palette create balsa background create
balsa design-system show balsa design-system apply balsa helpdiff is read-only and prints file-level patches from local source to current registry source.
update applies safe upstream changes and keeps locally edited or diverged source unless
replacement is explicitly forced. mcp exposes the same read-only discovery,
contract, project, design-system, and update-planning answers over stdio.
npm install
npm run fixtures:install
npm run checkCanonical source lives under src/components/ui, src/styles, src/theme, and
src/background for Vue, and packages/react for React. Registry, hosted payload, starter, and
fixture copies are generated — edit the canonical source, never the generated output.
npm run check is the full distribution gate: lint, tests, build, registry generation and
validation, derived contracts, documented examples, strict consumer type-checking, starter
synchronization, package packing, and release consistency.
The documentation website is maintained in a separate repository. This repository contains the complete open-source Balsa UI distribution.