Your first dashboard

The fastest way to understand butter is to build a small dashboard with it. This page walks you through the moves once: load the starter, rearrange, add a widget, change the theme, save your work. Once these feel natural the rest of the product is just more widgets.

1. Open a new tab

Hit ⌘T (or Ctrl+T ) — anywhere a new tab opens, butter is there. The first time, you'll see a welcome screen with two paths: a one-click starter dashboard, or pick widgets one at a time.

Click Set up a starter dashboard. You'll land on a five-widget layout: a clock and weather across the top, a Pomodoro on the right, a todo list on the left, and a scratchpad in the middle. Already usable; we'll customise from here.

2. Enter edit mode

Press E . The dashboard outlines its grid cells, drag-handles appear on every widget's title bar, and an X sits in the top-right of each card. You're now in edit mode — every widget can be dragged, resized, removed, or have its settings changed. Press E (or Esc ) again to lock it back in.

Drag the Pomodoro by its title bar to a new position. The grid snaps automatically — widget widths land on 4, 8, or 12 of the 12 columns, and rows snap to 80-pixel increments.

3. Resize a widget

Hover the corner of the Scratchpad. Three resize handles surface: the bottom-right corner (both axes), the right edge (width only), and the bottom edge (height only). Drag any one to resize.

Or keyboard it: Tab until the widget is focused, then arrow keys to nudge its position, Shift +arrows to resize.

4. Add a widget

Press A (or click the plus icon in the header). The widget picker opens with all fourteen widgets and a search field. Pick Quick Links — it lands at the bottom of your dashboard with four starter bookmarks already filled in.

Open its settings (gear icon on the widget's title bar in edit mode, or right-click the widget) to edit the links. Drag a row by its grip handle to reorder; click Add link to append a new one.

5. Change the theme

Press , to open Settings. The first section after Account is Theme — three buttons: Light, Dark, System. Pick whichever you'd like to live in.

Underneath, the Background section lets you choose between three modes:

• Default — the theme's own neutral background.
• Solid — pick from eight editor-inspired presets (Dracula, Tokyo Night, Solarized, GitHub, etc.) or open the custom hex picker for any colour at all.
• Gradient — six radial-bloom gradients per theme, modeled on the same editor palettes.

When you pick a solid colour, butter derives the widget surface and border colours from it on the fly — light hex backgrounds get white-tinted surfaces; dark hex backgrounds get black-tinted ones. The dashboard stays cohesive regardless of what you choose.

6. That's the whole product, really

There's no save button. Every drag, resize, setting change, and theme swap autosaves as you go — that's why the X removes a widget immediately and there's no "discard" path. Treat the dashboard as always-on.

From here, the rest is just more widgets, more layout, and a few more shortcuts. Three good places to go next:

• Keyboard shortcuts — the eight keys that cover everything you'll ever do.
• Layout & edit mode — every detail of the grid, snap behaviour, and resize handles.
• Connect GitHub — pull PRs awaiting your review into the dashboard. Same flow works for Linear.

Or copy an opinionated build

If "what should I put on it?" is the next question, the dev dashboard and focus dashboard guides each walk through a complete build you can copy outright. Five-minute reads, longer-term layouts.