Brand rules and guidelines

Each rule is one fact about your brand: the primary color, the minimum logo size, a word to avoid. A rule has a key (color.primary), a typed value (color, text, number, list or font), a sentence on when to use it, and any files it points at. The guideline pages are drawn from these rules, so changing a color in one place changes it on every page.

In the app, open the brand under Brands: its Rules tab holds every rule, and Release in its header puts them in front of readers. A new brand opens on its Overview, whose next steps say what to add. Scripts and agents write the same records:

artbucket rules set color.primary '#34a853' --type color --usage "Buttons, links, the mark's tile"
artbucket rules set color.primary '#5bc27a' --type color --context dark-background
curl 'https://assets.example.com/api/v1/brand/rules?context=dark-background'

A rule can be scoped to a context. Asking for one returns one rule per key: the context’s own where it has one, the default otherwise.

The guidelines page

Open a brand from Brands in the sidebar. The header shows which release readers see, whether there are unreleased changes, and where the brand is live (BrandHub, portals, or only the team). It has three buttons:

Use this brand: the MCP address, brand.json and llms.txt on BrandHub, the design tokens, DESIGN.md, the Office templates once released, and Start from this brand to copy it into a new one.
Edit: the three ways to change the pages, below.
Release: puts the changes in front of readers. It shows only while readers don’t see the latest.

The brand’s menu, at the end of the header, has the rest: Theme, Insights, Settings, Connect Git, pinning it to the sidebar and opening it in the catalog. Below the header are six tabs, in the order a brand is made:

Tab	What it is for	Address
Overview	What the brand is, its colors and typefaces, its latest release, and its health: the Brand Agent Score and whether it is read	`/brands/{slug}`
Rules	Every rule, by section, edited in place by whoever may edit the brand; its tokens in every format above them	`/brands/{slug}/rules`
Assets	The files its rules hold and its pages show	`/brands/{slug}/assets`
Guidelines	The pages as readers see them: the live release, or the draft for editors, labeled, with a switch between them	`/brands/{slug}/guidelines`
Releases	Each release with its note and what it changed, and the form for the next	`/brands/{slug}/releases`
Sharing	Who reads it outside the team: BrandHub, public or private, the portals showing it, and the addresses agents and code read	`/brands/{slug}/sharing`

On the Rules tab, click a value to change it. Add a rule, or /, adds one from named building blocks such as a brand color, clear space, logo don’ts, a type scale or words to avoid. A rule’s details take versions for a context, a spec and files; drag a rule to reorder it, or use its menu to move, duplicate or delete it, with Undo. /brands/{slug}/rules#rule-{key} opens one rule.

Colors show as a table, by their spec’s group, each light value beside its dark one: its dark-background version, or the brand’s own dark context. A dark value, in a color’s details, adds one. Text colors (ink, muted, nightInk, or a color’s pair) show their contrast on their group’s ground in both themes. An attached asset can name a rendition (w_512,f_png): agents then get that exact URL.

Brand pages

Edit, in the brand’s header and on the Guidelines tab, opens the three ways to change the pages, over the pages as readers see them (/brands/{slug}/guidelines?ways=1): an agent over MCP, with the pages tools (list_pages, get_page, save_page, edit_page, generate_pages, delete_page, preview_page, list_templates), Git (brand as code), or Eject to code. The pages API and MCP write the same pages. The rules are edited on the Rules tab and the look on Theme (/brands/{slug}/theme).

A brand with no pages gets them laid out from its rules by generate_pages, or POST /api/v1/brands/{slug}/pages: color.primary, color.secondary, color.dark, type.heading, type.body, logo.primary and tone.voice make the cover and the pages after it, and a brand with none of them starts from a cover. Set them on the Rules tab, like any other. The score, of 100, weighs the brand’s steps to being worth sharing (colors, typefaces, logo, voice, a look, pages, a release, a portal) by what each gives an agent working from it; the brand’s Overview shows it, and its own page (/brands/{slug}/score, from the Overview) lists every step with what it gives, the two fixes worth the most, a prompt that hands them to an agent connected over MCP, and BrandHub’s public score for the domain the organization proved. Agents read the same score and steps with brand_status, or GET /api/v1/brands/{slug}/status.

Review comments on the pages are read and answered on the Guidelines tab: Comments in its bar opens them for the page on show (?comments=1), with the other pages that have open threads one click away. Agents read and write them over MCP (list_comments, add_comment, update_comment, delete_comment).

An embed section takes a link: a YouTube, Vimeo or Loom page becomes its player. Readers see a placeholder naming the service until they click to load it, so their browser contacts YouTube, Vimeo, Loom, Figma or Google only when they choose.

The rules are the content; pages lay them out for people. A brand’s pages form a tree, up to three levels deep (Overview, then Identity with Color, Logo and Type under it), and each page is sections built from templates: a cover, a palette, type specimens, logo rules, do’s and don’ts, a gallery, a live collection, an icon set (what the library tags icon, which an icon pack import tags). A section shows rules by key and never copies a value, so change color.primary and every page that shows it follows.

artbucket templates                  # what each template shows and binds
artbucket pages generate             # a first layout from the rules
artbucket page save color color.json # make or replace a page whole
artbucket page color                 # a page as Markdown

A page reads as a chapter of the book (layout: book, the default: the nav beside it, on-this-page, and the next page at its foot) or as a front (layout: landing: none of those, for a home or a campaign page). Its audience says who may read it on a portal, and hidden keeps it from readers altogether. The theme (/api/v1/brands/{slug}/theme) says which rules play which part (accent, grounds, ink, faces, logo) and sets the measure, navigation and on-this-page for every page. Agents build all of it over MCP.

Fonts

A font rule’s files are its typeface: pages set the face in them, served from /a/ like any asset, and readers’ browsers call no one else. A rule whose spec.source is google gets its files from Google Fonts on the server: when it is written without any (the brand’s setup, a template, the rule editor, set_rules), and again before each release. Brands from before the server did this get theirs from its sweep, at start and every six hours, a batch at a time: the files go onto the draft’s rules and into every release’s stored rules, so what readers see keeps its look, with no new version. The files are the family’s every weight and italic, in the library, as Import from Google Fonts, import_google_font and POST /api/v1/fonts/google make them; brought in with a key that may only propose, they wait for approval like anything it adds. A rule still without files (Google out of reach, someone who can’t add to the library, a brand kept in Git, whose files are its repository’s to hold) is set in its spec.fallback. For a brand kept in Git the sweep patches its releases only, and its next push releases what the repository holds. Only the font picker and a brand’s setup, in the app, show families straight from Google while someone chooses.

Releasing

Every edit to the rules, the pages or the theme is a draft. Releasing makes the brand as it stands the version portals show, until the next release. The command and the endpoint are still called publish:

artbucket publish --note "A warmer primary, and a page on motion"
curl -X POST https://assets.example.com/api/v1/brands/default/publish \
  -H 'Content-Type: application/json' -d '{"note": "A warmer primary"}'

The note (and an optional image beside it) is what readers see in What’s new, with what the release changed since the one before: rules and pages added, changed and removed. The answer names the portals showing the brand. Releasing with nothing changed does nothing. It takes Editor on the brand.

A release is numbered as its version (@5). The brand’s Releases tab (/brands/{slug}/releases) lists them, each with its note and what it changed; Release in the brand’s header opens the form (/brands/{slug}/releases/new): the note, what changes since the last release line by line (a color’s value before and after, a page’s sections edited), and the Brand Agent Score before and after. While only the team reads the brand (no portal shows it, and it is private on BrandHub), the form asks who should see it: a portal of its own, open to the project’s members or to anyone, for whoever manages portals, and Public on BrandHub for whoever may release the brand, applied once the release lands.

Design tokens

GET /api/v1/brand/tokens?format=css is the brand as CSS custom properties with @font-face; format=json is W3C design tokens; format=designmd is a DESIGN.md for coding agents, the tokens with the brand’s guidance as prose, to keep at a repository’s root. Standards has every format and how rules become each.

Office templates

A release is also a PowerPoint template (.potx) and a Word template (.dotx), for the people who make decks and documents rather than code. Every install has it. A server that sells plans leaves templates out of a plan’s features to turn them off, your own templates below and a portal’s included; BrandHub’s press kit stays. Members get them on Brand files, in the sidebar, with what each holds and the brand’s share card and press kit, and under Use this brand; portal visitors beside the logo kit, on a logos section that offers it.

curl -OJ "https://assets.example.com/api/v1/brand/office?brand=acme&format=potx"
curl -OJ "https://assets.example.com/api/v1/brand/office?brand=acme&format=dotx&version=4"

Without version, the release readers see; a brand edited and never released has no template. On a portal, GET /api/v1/portal/{slug}/brands/{brand}/office?format=potx, behind the portal’s door.

Both carry the brand as an Office theme, the one PowerPoint and Word list under Design and Page Layout:

Office slot	From the release
Text/Background dark 1, light 1 (`dk1`, `lt1`)	The ink and the paper, as the brand’s pages wear them (Theme)
Dark 2, light 2 (`dk2`, `lt2`)	The dark color and the panel; on a dark paper, the panel and the quiet text
Accent 1	The accent
Accents 2 to 6	The palette’s other colors, in its order, then tints and shades of the accent
Hyperlink, followed hyperlink	The accent as text, the quiet text
Headings, body fonts	The heading and text faces

The deck has a slide master with three layouts (title, title and content, section on the accent) and opens on a title slide with the brand’s name. The document has Title and Heading 1 to 3 in the heading face, body text in the text face, on A4. The logo, the theme’s logo rule’s first file, sits on the master, large on the title layout and in the document’s header, drawn as a PNG; a logo shown only stays out.

Office can’t load a web font from a template, so the theme names each family and says what kind of face it is (sans, serif or mono, read from its fallback): where the family isn’t installed, Office sets a face of that kind, and Word the fallback’s first named family. Install the brand’s fonts for the real thing; the typography section offers them.

Google Slides opens a .potx uploaded to Drive (Open with, Google Slides), and LibreOffice Impress opens one too: there is no Slides integration to set up. One release is one file byte for byte, so a download sends an ETag and the same copy answers 304.

Your own templates

A deck an agency designed, a letterhead, a budget sheet: upload the PowerPoint, Word or Excel file (.potx, .pptx, .dotx, .docx, .xltx, .xlsx) to the library and put it on one of the brand’s rules, as a logo is. A templates.slides rule that says “Start every deck from this one” is the usual place. Once released, it is listed on Brand files beside the generated ones, and each download wears that release:

every theme part takes the release’s colors and its heading and text families, as in the table above; script faces (Japanese, Arabic…) stay
each image the library has, matched by its bytes, is replaced by that asset’s current version: a new logo reaches every deck without anyone opening it. A replacement in another format is drawn as the image’s own
nothing else changes: the layouts, placeholders, text and effects stay as the designer made them

The file itself isn’t rewritten: like the generated ones, each download is made from the release it asks for, so an older release still gives its own. The file has to be approved, usable now and free to leave the team, and the caller has to be able to see it; a new version of the file takes over as soon as it is current. An image is replaced only by a version that may leave too. On the brand’s pages, the file’s tile on its rule downloads it this way, and portal visitors get it behind the portal’s door (GET /api/v1/portal/{slug}/brands/{brand}/office/templates/{id}).

curl "https://assets.example.com/api/v1/brand/office/templates?brand=acme"
curl -OJ "https://assets.example.com/api/v1/brand/office/templates/{id}?brand=acme"

The list says, for each file, what won’t follow a release: colors and fonts written on shapes and text instead of taken from the theme (a color of the brand’s palette counts as the brand’s), images the library doesn’t have, and a file with no theme at all. follows is true when there is none of that. Ask the designer to use the theme’s colors and fonts (Design, Variants in PowerPoint; Design, Colors and Fonts in Word) and the library’s logo.

Brands and history

A project can hold several brands, one of them the default. Every change is kept, like a shared doc: edits close together are one version, a named version is a checkpoint, and any version can be restored, as a new version. Released versions are marked; a restore is a draft like any edit, until it is released.

curl https://assets.example.com/api/v1/brands/default/versions
curl -X POST https://assets.example.com/api/v1/brands/default/versions/3/restore

Set up your brand

From an empty project to a released brand.

Run a rebrand

Draft, review and release on one day.

Portals

Where people outside the team read the brand.

Brand as code

The brand in a Git repository, synced both ways.