Update visible interfaces in Lite and but.dev using @gitbutler/ui-react. It guides component reuse, relevant design references, concise screen text, and visual checks in light and dark themes for forms, dialogs, notifications, and other surfaces.
Use when changing what users see in an app built on `@gitbutler/ui-react` — Lite, 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.
Review the instructions the agent will receive before you install.
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.
Change what the task needs. Older screens may not follow these notes; leave them alone unless the task is to fix them.
@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:
packages/ui-react/src/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.
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.
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.
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.
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Manage version control through GitButler’s but CLI. Select files or hunks, meaning sections of a diff, for commits; organize dependent branches, split or combine history, resolve conflicts, and create pull requests using task-specific command workflows.
Review captured agent sessions related to a GitButler branch, pull request, or change. Start with a chronological overview of previous discussions and actions, then inspect specific turns when the rationale or supporting evidence needs clarification.
Create, update, run, and debug shell-based performance scenarios for the but CLI. It separates repository setup from the operation being measured, uses Hyperfine for timing, and guides focused validation and inspection of test output.
Implement or modify GitButler’s but commands using its established structure. It covers typed arguments, input validation, execution, and human-readable, shell, or JSON output, while keeping operations usable from the terminal interface.
Prevent and investigate excessive rendering in Lite React screens. It guides data transformations, context use, and store subscriptions, then checks compiler output and measures rendering time before and after changes to verify their effect.
Capture before and after screenshots of Lite UI changes on a local machine, compare the images, and publish changed screens to a pull request. It also guides screenshot coverage checks and updates to an existing comment.