# Gitbutler UI

Use when changing what users see in an app built on `@gitbutler/ui-react`, such as the...

- Repository: https://github.com/gitbutlerapp/gitbutler (21903 stars)
- Category: Design
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add gitbutlerapp/gitbutler --skill gitbutler-ui -g -a claude-code -y`
Codex: `npx skills add gitbutlerapp/gitbutler --skill gitbutler-ui -g -a codex -y`
Cursor: `npx skills add gitbutlerapp/gitbutler --skill gitbutler-ui -g -a cursor -y`
Gemini CLI: `npx skills add gitbutlerapp/gitbutler --skill gitbutler-ui -g -a gemini-cli -y`

## Description

Use when changing what users see in an app built on `@gitbutler/ui-react`, such as the but.dev web app: adding or restyling a component, modal, form, list, empty state or toast, or writing the words on screen. Not for logic, data or backend work, even inside a UI file.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Building GitButler UI

Work as you would in any codebase: find the closest thing that already
exists and copy it. These notes say where to look and what to check. They are
not a gate to clear before starting.

## Scope

Change what the task needs. Older screens may not follow these notes; leave
them alone unless the task is to fix them.

## Start from the library

`@gitbutler/ui-react` has the controls: `Button`, `Popup` (modals, dropdowns),
`Select`, `Field`, `Checkbox`, `Switch`, `Tooltip`, `EmptyState`, `Snackbar`
(raised through the `Snackbars` stack), `Toasts`, `Banner` and more. Use them
rather than a control styled in a feature's CSS. Find a surface that already
uses the ones you need and follow its structure.

The source is the reference, because it is the version you build with:

- In the gitbutler repository: `packages/ui-react/src/`
- In but.dev: `web/node_modules/@gitbutler/ui-react/src/`

Each component's JSDoc says what its props do. The Storybook MCP server
(`docs-show`) and
<https://master--6ab536f5f40e41db628ccf1b.chromatic.com/manifests/components.json>
have the same docs with examples; use them when they answer, and go back to the
source when they don't. Don't wait on them.

Each component's stories open with `Default`, its simplest use and its props;
the ones after it are examples, the component put to work the way an app
writes it. For a whole surface, find the closest example under its outermost
component (a confirmation is Modal's, a picker Popup's or PickerDialog's),
copy it and change what differs.

When nothing fits, build the smallest thing that works and say so in the PR
description: what was needed, which components you tried.

## Read the design pages you need

The rest: https://github.com/gitbutlerapp/gitbutler/blob/HEAD/packages/ui-react/skill/SKILL.md