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