brand.yamlis the only file that must be there.- Only files directly in
rules/andpages/are read, not in folders under them. Anything else in the folder (a README, a.gitignore) is left alone. .ymlis read like.yaml, but a name may be there once:rules/color.yamlbesiderules/color.ymlis an error. Artbucket writes new files as.yaml; the CLI’s pull keeps a.ymlfile’s name.assets/may have folders of its own (assets/logos/mark.svg).- A request carries at most 500 files, each at most 2 MB.
brand.yaml
brand.yaml
Any other key is an error. The comment line on top is what Artbucket writes;
it is a comment like any other, yours to keep or change.
The order of rules
rules lists each file of rules/ once, by its name without .yaml. A
name with no file is an error; a file it leaves out is read after the listed
ones, in alphabetical order, with a warning. Without rules, the files are
read in alphabetical order. Within a file, rules keep the order they are
written in.
The page tree
pages is the navigation, in reading order. Each entry is a page’s slug, or
a page with pages under it as a map of one key:
- Every slug names a file in
pages/, and is in the tree once. - Three levels at most.
- A page file the tree leaves out comes last, at the top level, with a
warning. Without
pages, every page sits at the top, in alphabetical order. - Where a page sits is the tree’s alone: a page file can’t say
parentorposition.
The theme
Which rules play which part, and the measure and chrome of every page. Each part names a rule by key; anything left out is read from the rules (an accent fromcolor.primary, faces from the font rules’ roles and names).
A part naming a rule that isn’t there, or isn’t the kind it needs (a color
rule for
accent, a font rule for head, a rule with a file for logo), is
an error. Colors that read badly together (text with too little contrast on
its ground) are a warning, with the ratio found and the one needed.
Rule files
A rule file is a map of rules by key. The file’s name is the group: the first segment of each key it holds, socolor.primary belongs in
rules/color.yaml.
rules/color.yaml
Any other field is an error.
Values
A font’s files are its assets, so readers see the face without installing
it, and design tokens carry them as
@font-face.
How a list reads follows its key’s last segment: never, neverDo,
dont, avoid and the like are don’ts; always, do, prefer are do’s;
a list of numbers under type. (or named scale or sizes) is a type
scale. Anything else is a plain list.
Specs
A gradient makes the color a gradient, its
value the solid for where a
gradient can’t go:
pair and the stops name color rules of this brand; any other key is an
error.
Assets
A rule points at up to 24 files, each once. Each is a path underassets/
in the folder, an asset’s id in the library, or either with a rendition:
Contexts
A context version holds the rule as it is in one context:dark-background,
instagram-story, print, a language. It takes type, label, value,
usage, spec and assets, and keeps the rule’s type unless it says
another. Asking for a context gets each rule’s version there, and the default
of the rest.
type and contexts,
and nothing else.
Keys Artbucket reads
Any key works. These are the ones the pages, the theme, the Brand Agent Score and the exports look for by name:
brand.json lists every key it reads,
with the alternatives it accepts.
Page files
A page file is one page: its name is the page’s slug (lowercase words joined by-, up to 60 characters), and it sits where brand.yaml’s tree puts it.
pages/logo.yaml
slug, parent and position are errors: the file’s name is its slug, and
the tree places it.
Sections
Every section has atemplate, and takes the same fields whatever its
template:
Links in Markdown and items go to
https://, mailto:, or inside the brand:
/page, /page#section, #section.
Items
What a template lists, where it lists things. Which fields each needs is in the templates table.Templates
Defaults are the width, columns and tone a section has when it sets none.
A template that binds none takes no
keys and no contexts; one that lists
nothing takes no items. verdict is for dodont (and dont in logos),
span for gallery, at for annotated, level for cards.
Ids
A section’s id, when the file leaves it out, is its template’s name, then-2, -3 for the next of the same template on the page: the first palette
is palette, the second palette-2. Artbucket leaves those out when it
writes, and writes any other id. Give a section an id of its own when
something links to it and it might move.
Assets
Anywhere the API takes an asset’s id, a file takes a path underassets/
instead: a rule’s assets, a color’s spec.texture, the theme’s device, a
page’s cover, a section’s props.image, props.video and props.asset,
background.image, and an item’s asset. An asset id works too, for a file
in the library that isn’t in the repository.
Paths are matched to the library by content: whoever sends the files sends
each file’s SHA-256 too, and Artbucket finds the asset holding those bytes.
A file it doesn’t have yet is named as missing, while the rest still checks:
upload it, then send the files again (the sync API).
The CLI does both for you.
Exporting writes an asset the repository holds as its path, and any other as
its id. Asked to, an export also gives every asset a path under assets/,
to bring them into the repository.
What a file leaves out
Artbucket writes nothing that is at its default, and reads a missing field as its default:- A rule: no
label,usage,specorassetswhen there are none. A context version leaves outtypewhen it is the rule’s. - A page:
audience: everyone,layout: book,tabsandhiddenwhen false. - A section: its natural
id, an emptytitleorbody, the template’s width, columns and tone,hidden: false, and emptykeys,itemsorprops. brand.yaml: an empty theme,ruleswith no rule files,pageswith no pages.
keys: [color.primary, color.ink]); the page tree stays a tree.
Comments and layout
A file whose meaning didn’t change is never rewritten. Comments, key order, quoting and flow style ({ unit: px } or a block) stay as you wrote them.
Only a file that says something new is written again, and then in
Artbucket’s layout.
Problems
Every problem comes back at its file and line, with the path to it in the file:brand.yaml’s lists, a rule in another group’s file, a link to
a page or section that isn’t there or is hidden, units that mix in one
section, colors with too little contrast, a page that opens with no picture,
two grounds of a kind in a row.
A complete example
A brand of eight rule files and six pages, with every part brand.json reads (what it exports). It checks with no warnings.artbucket brand pull brand --brand acme --assets writes its folder, files
included (CLI).