Skip to content
bref / ui

A Svelte-first, human-first, agent-first UI library.

Star

Own the code

Copy Bref components into your project and own their source.

Copy components

Run from a project containing package.json, using Node.js:

Bash
npm install bref-ui
npx bref-ui init
npx bref-ui add button
npx bref-ui --help

add button automatically copies Icon and Theme dependencies. add previews planned files and requests approval before copying or overwriting.

Import paths

#bref imports local source you own; #bref/* maps its destination.

init adds concrete package.json imports, defaulting to src/lib/ui or a ui directory inside the #lib/* target. Existing Bref imports are preserved; no separate configuration file is used.

JSON
"imports": {
  "#bref": "./src/lib/ui/index.js",
  "#bref/*": "./src/lib/ui/*"
}

To choose a custom destination, edit both paths before running add:

JSON
"imports": {
  "#bref": "./src/components/ui/index.js",
  "#bref/*": "./src/components/ui/*"
}

Project files

Before the commands, in an existing Svelte project:

my-app/
├── package.json
└── src/
    ├── lib/
    │   └── …
    └── routes/
        └── +page.svelte

After npm install, init and add button:

my-app/
├── package.json          # init adds #bref imports
├── package-lock.json     # npm install
├── node_modules/         # npm install
└── src/
    ├── lib/
    │   ├── …
    │   └── ui/           # add button
    │       ├── index.ts
    │       ├── button/
    │       │   └── button.svelte
    │       ├── icon/
    │       │   └── icon.svelte
    │       └── theme/
    │           ├── cli-theme.svelte
    │           ├── colors.svelte
    │           ├── surface.ts
    │           └── …
    └── routes/
        └── +page.svelte

init copies no files. The CLI writes index.ts ; the index.js import mapping resolves to that source through TypeScript/Svelte tooling.

Use copied components

Import the copied components through #bref; keep type imports from bref-ui/types.

Svelte
<script lang="ts">
	// 📦 Old way: packaged components
	import { Button, Theme } from 'bref-ui';
	import type { ButtonProps } from 'bref-ui/types';
</script>

Svelte
<script lang="ts">
	// ✅ Own the code: import copied components via #bref
	import { Button, Theme } from '#bref';
	import type { ButtonProps } from 'bref-ui/types';
</script>

<Theme>
	<Button label="Save" />
</Theme>

Copying Theme makes its source available; render it once at the application root.

Customize copied Theme

The included Theme is default-only without a palette prop. Customize its CSS in theme/colors.svelte inside the copied directory. For the packaged Theme's palette prop and live controls, see Use the package .