Brand as code
A brand can live in a Git repository as well as in Artbucket: its rules, pages and theme as YAML a person reads and reviews, beside the files they point at. Change it in the repository, through a pull request, or in the app: each side’s changes reach the other, and a change both sides made to the same rule is named, not lost.
brand/ brand.yaml the brand's slug and name, its theme, the order of rules/, the page tree rules/color.yaml the rules whose key starts with color. rules/logo.yaml pages/overview.yaml a page: its fields and sections pages/logo.yaml assets/logo.svg files the rules and pages point atcolor.primary: type: color label: Acme blue value: "#1f6feb" usage: Buttons, links and the mark's tile. contexts: dark-background: value: "#58a6ff"The files say what the API takes, minus every default, so a brand written out, read back and written again is the same bytes. A file whose meaning didn’t change is never rewritten: its comments and its layout stay as a person left them. The brand folder documents every file and key.
When to use it
Section titled “When to use it”- A design system or a product’s brand, where the brand sits beside the code that uses it, and changes go through review like the code does.
- An open-source project’s brand, where anyone proposes a change by pull request and the maintainers merge it.
- Many brands kept the same way, generated or checked by scripts.
- A record of every change outside the app, in the history your team already reads.
A brand edited only by a brand team in the app needs none of it: the app keeps every version itself (history).
The two-way model
Section titled “The two-way model”Artbucket stores, for each brand kept in a repository, where its files live (the repository, a branch, a folder) and the files both sides last agreed on. Each import is a three-way merge against that agreement, a piece at a time: each rule (by key and context), each page’s own fields and each of its sections (by id), each theme setting, the name, and the order of rules, of pages and of a page’s sections. A person rewording one section in the app and a pull request adding another to the same page both land.
- A piece only one side changed takes that side’s change.
- A piece both sides changed the same way is that change.
- A piece both sides changed differently is a conflict: the repository’s side wins, since what reached its branch was reviewed there. The answer names each conflict, and the app’s side is not lost: the version before the import is in the brand’s history, a restore away.
The agreement is recorded by a Git integration, at each commit it syncs. The CLI keeps its own for the folder it pulls into, so a push from your machine merges the same way. A CI job has none, so its files are taken whole: the repository is then the source of truth, and an edit made in the app is undone by the next push from CI (what a push overwrites).
An import is written as a version of the brand’s history, so it is undone like any other edit. With the commit’s message, that version is named after its first line, a checkpoint of its own. Nothing reaches readers until someone releases it: an import updates the draft unless it is asked to release too.
When the brand changes in the app, it is pending: the repository lacks those changes until they are exported and committed back.
Ways to sync
Section titled “Ways to sync”| Who talks to Git | Direction | Pull requests | |
|---|---|---|---|
| The CLI, by hand | You | Pull and push | |
| A CI job | Your CI | Push from the main branch | A check on the files |
| A Git integration (your own) | The integration | Both ways, as changes happen | A check, a preview link and a comment |
All three call the same API. Artbucket never talks to the Git host itself: whoever holds the host’s credentials (an app, a CI job, you) does.
From the app
Section titled “From the app”Where the server has a Git integration (GIT_CONNECT_URL, see
Environment), a project admin reaches it from
these places:
- New brand, From a Git repository: bring in a brand a repository already
holds (its
brand.yaml, pages and files), or start a new brand and keep it in a repository from the first edit. - A brand’s header: Connect Git in the brand’s menu, and Git among the ways Edit opens, until the brand is kept somewhere; then the repository, and whether both sides are in step.
The integration sends you back to the brand’s Overview, which says when the first sync has landed and offers Release while readers don’t see it yet. On Home’s first-run checklist, the path for a product’s brand and design system offers My brand is already in a repository, which brings it in.
From CI
Section titled “From CI”Without a Git integration, a CI job pushes the brand’s folder when it changes on the main branch, and checks it on pull requests. The CLI page has GitHub Actions and GitLab CI recipes.
A README badge
Section titled “A README badge”A public, released brand has a badge on BrandHub at /{org}/{brand}/badge.svg.
It wears the brand: its mark and its name, the release that is live on its
primary color, and a check once its organization is
verified.
The brand’s Sharing tab, under BrandHub, gives its Markdown:
[](https://hub.example.com/acme/acme)The mark is the image of a logo rule named for one (logo.mark, logo.icon,
logo.symbol), drawn on a white tile. A wordmark would be unreadable that
small, so a brand without a mark shows Artbucket’s icon.
Point the link at your guidelines instead, if you would rather send readers there. The badge is 20px high, so it sits in a row of shields.io badges. It follows each release and each change of color, answers for public brands only, and showing it is not counted as a read of the brand.