Contributing

How to work on buttery itself: setting up, the commands, the rules a change follows, and how to commit it.

buttery is a pnpm monorepo: the packages under packages/, and this site, the starter, the templates and the demos under apps/. This page covers what a change needs before it's ready; AGENTS.md in the repository has the full rules, for people and coding agents alike.

Set up

Clone and install

bash

git clone https://github.com/aliboIly/buttery.git
cd buttery
pnpm install

Installation lists the Node and pnpm versions it needs.

Run this site
bash
```
pnpm dev
```
It has a page for every component, with the examples and checks you'll change. A change to a package shows on its page as you save.

Commands

Command	What it does
`pnpm dev`	Runs this site, with a page for every component
`pnpm check`	Everything a change has to pass: the authorship and private-path checks, types, lint, formatting, unit and browser tests, the docs check and the layout checks at two widths
`pnpm test:layout`	The layout checks across every width, theme and density, in Chromium and WebKit
`pnpm docs:build`	This site as static files in `apps/docs/dist`, which each push to `main` deploys to GitHub Pages
`pnpm new-component Name`	A new component folder that already follows the component contract
`pnpm new-app name --template dashboard`	A new app copied from a template: `blank` (the starter, the default), `dashboard`, `editor` or `marketing`

The rules a change follows

Tokens only
No raw colors, sizes, radii, shadows, durations or z-indexes outside the token source. Colors and the other Foundations pages list them.
The layout contract
Flow layout with gaps, no outer margins, sizes from tokens and container queries. The layout contract has all thirteen rules.
The component contract
ref as a prop, controlled and uncontrolled, one prop vocabulary, JSDoc on every export and prop, keyboard and screen reader support, and it works with motion off.
The motion rules
Direct manipulation is instant, discrete changes spring and exits are faster than entrances. Motion principles has the rest.

A change to a component changes its page, examples and metadata with it, and the docs check fails when they don't agree.

Commits

One focused change per commit, with a conventional prefix and a subject of 72 characters at most, in the imperative:

bash

git commit -m "feat(react): give Slider a label on top"
git commit -m "fix(core): keep a Morph's height while its content swaps"

Releasing

Set the version and write its notes
Put the new version in every packages/*/package.json, and add apps/docs/content/whats-new/<version>.md with the release's version, date, title, a one-sentence summary, the examples that show it, and two or three highlights. The docs check holds every field.
Prove the packages from their tarballs
bash
```
pnpm check
pnpm test:layout
pnpm test:apps
```
pnpm test:apps packs every package and makes an app from each template outside the repository from those tarballs; they're the files to publish, so a published package is one a fresh app has already passed with.
Publish, then tag
bash
```
npm publish butteryui-core-1.1.0.tgz --access public
git tag -a v1.1.0 -m "v1.1.0: What it brings"
git push origin main v1.1.0
```
One npm publish per tarball. The release workflow publishes the GitHub release from the tag, with the same notes as What's new and a link to them, and the push to main deploys this site.

Roadmap
What's being built now, what's planned after it, the ideas for later, and every release so far.
The layout contract
The 13 rules every buttery screen follows, so nothing overlaps, overflows or shifts, and how they're checked.