Brand kits

A brand kit is your organisation’s shared colours, text styles, images, components and fonts. Designers use its items in the editor; when a template is published, it takes the kit’s current items. The editor manages kits too: the API is for keeping a kit in step with another system, such as your brand guidelines.

Make a kit and fill it

curl -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"name": "Acme", "description": "The Acme house style"}' "$PAPRIKA_URL/v1/brandkits"

{
  "id": "acme",
  "name": "Acme",
  "description": "The Acme house style",
  "revision": 1,
  "swatches": [],
  "paragraphStyles": [],
  "characterStyles": [],
  "images": [],
  "components": [],
  "fonts": []
}

The kit’s id is made from its name. Add an item with a PUT to its kind and an id of your choice; each item has a description, its usage rule, which the editor shows to designers. A swatch:

curl -X PUT -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"name": "Acme red", "kind": "rgb", "value": "#c8102e", "description": "Headlines and accents only"}' "$PAPRIKA_URL/v1/brandkits/acme/swatches/acme-red"

A paragraph style, in a font of the font library, its colour the swatch:

curl -X PUT -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"name": "Headline", "family": "Liberation Sans", "weight": 700, "size": 24, "color": {"swatch": "acme-red"}, "description": "One per page"}' "$PAPRIKA_URL/v1/brandkits/acme/paragraphStyles/headline"

An image, its name and description in the address:

curl -X PUT -H "Authorization: Bearer $PAPRIKA_KEY" --data-binary @logo.png "$PAPRIKA_URL/v1/brandkits/acme/images/logo?name=Logo&description=On%20light%20backgrounds"

A component, as a template holds it: its parts in the kit’s swatches, styles and images and the library’s fonts, and fields, the definitions of the fields its parts show. A template placing it gets the fields it hasn’t got:

curl -X PUT -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"name": "Price tag", "width": 120, "height": 40, "frames": [{"id": "price", "type": "text", "x": 0, "y": 0, "w": 120, "h": 40, "paragraphs": [{"paragraphStyle": "headline", "runs": [{"text": "{{price}}"}]}]}], "fields": {"price": {"type": "text", "required": true, "label": "Price"}}, "description": "One per product"}' "$PAPRIKA_URL/v1/brandkits/acme/components/price-tag"

A component whose parts use a swatch, style or image the kit hasn’t got, a font that isn’t in the library, or a field it doesn’t define is refused (422 kit-invalid). Designers usually add components from the editor, which sends what they use along with them.

The kinds are swatches, paragraphStyles, characterStyles, images, components and fonts (a library font, {"sha256": "…"}). Every change makes a new revision of the kit; GET /v1/brandkits/acme shows it with all its items, GET /v1/brandkits lists your kits.

When the kit changes

A published version never changes: it keeps the kit’s items as they were. When a brand colour changes, change it once in the kit, then publish a new version of every template whose latest version used an older revision:

curl -X POST -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/brandkits/acme/republish"

{ "published": [], "failed": [], "current": [] }

published lists the templates given a new version, current those already up to date, and failed those the change breaks, with the layout errors: a bigger headline that no longer fits, say. Those keep their version until a designer fixes them.

Which templates’ latest versions use an item:

curl -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/brandkits/acme/components/price-tag/templates"

[]

Deleting an item, or a kit, that templates’ latest versions use is refused (409 kit-item-in-use, kit-in-use) with the templates; add ?confirm=true to delete it anyway. The templates keep their copies until they are next published.