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
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 shared design language is the library's DESIGN.md, beside src/ in the
same two places: an index of one page per topic, in design/, each saying
when to read it. Read the pages for what you are building, not all of them.
In Storybook they are the Design section, and docs-list lists them.
Each app keeps its own choices in its own DESIGN.md: Lite's is
apps/lite/DESIGN.md, but.dev's is at its repository root.
Words
Short and plain. A label is one to three words; a hint is one sentence. Call
things what the rest of the app calls them. Say what the user can't already see
on screen, once, without parentheses.
Check it
Look at the result in light and dark, and keep one screenshot. In the
gitbutler repository a component's story runs with pnpm -F @gitbutler/lite demos; apps/lite/AGENTS.md has how to reach a single story.