> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tastelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract a brand from a brand kit

> Turn a brand guidelines PDF into a structured brand kit

Use a brand kit to give your agents a brand straight from its guidelines PDF (a brand book, brand toolkit, or identity deck), so they can create new assets that follow it. The kit returns the profile and voice, the palette with its proportions, typography, logo variants and misuse, photography, graphics, layout, buttons, cards, motion, and the book's own rules.

A brand kit is a submission like a [website extraction](https://docs.tastelabs.com/concepts/submissions.md), but its `result.design_system` has `kind: "brand_kit"` and its own shape. Use it when the source of truth is the guidelines document, not a website.

## Extract a brand kit

Upload the PDF as `multipart/form-data` in a field named `file`:

```bash theme={null}
curl -X POST https://api.tastelabs.com/design/submissions/brand-kit \
  -H "X-API-Key: $TASTE_API_KEY" \
  -F "file=@brand-guidelines.pdf"
```

Poll the returned `submission_id` until `status` is `completed` or `failed`, following the [submission lifecycle](https://docs.tastelabs.com/concepts/submissions.md#polling-for-the-result). On completion, read `result.design_system`.

To read only part of a finished kit, pass its section names to the result endpoint, for example `?sections=colors,buttons`. Brand kits appear in [`GET /design/submissions`](https://docs.tastelabs.com/api-reference/endpoint/list-submissions) next to website extractions; filter them with `?kind=brand_kit`. A brand kit's `source_url` is `file://` followed by the uploaded file name.

> [!NOTE]
>
> The file must be a PDF of up to 50 MB. The extractor reads up to the first 150 pages. Every upload is a fresh extraction: brand kits are never served from cache.

## Give it to your agents

Hand your agent the sections a task needs instead of the whole kit. Fetch them with the `sections` query parameter:

```bash theme={null}
curl "https://api.tastelabs.com/design/submissions/$SUBMISSION_ID/result?sections=colors,typography,logo,rules" \
  -H "X-API-Key: $TASTE_API_KEY"
```

| To create | Pass these sections |
| - | - |
| Social posts and ads | `colors`, `typography`, `logo`, `photography`, `graphics`, `rules` |
| Web pages and UI | `colors`, `typography`, `buttons`, `cards`, `layout`, `rules` |
| Copy | `profile`, `rules` |
| Motion and video | `motion`, `colors`, `logo`, `rules` |

A few fields help most:

* **`colors.palette[].proportion`**: tell the agent how much of each color to use, not only which colors exist. Prefer `stated`, then `drawn`.
* **`logo.misuse`** and **`rules`** with `kind: "dont"`: the book's own list of what not to do. Ask the agent to check its output against them.
* **`buttons[].css`** and **`cards[].css`**: drop-in styles for UI work, already converted from the PDF.
* **`asset.url`**: real logos, graphics, and photos from the book. Use them as references or as files to place in the design.

## Read the result

The following example shows one palette color. Other sections are omitted.

```json theme={null}
{
  "kind": "brand_kit",
  "colors": {
    "palette": [
      {
        "name": "Ink",
        "hex": "#010103",
        "group": "primary",
        "cmyk": null,
        "rgb": null,
        "proportion": { "stated": 0.85, "drawn": 0.339 },
        "when_to_use": ["Use as the ground, covering about 85% of every surface."],
        "when_to_use_source": "declared"
      }
    ]
  }
}
```

| Field | Meaning |
| - | - |
| `kind` | Always `brand_kit`. Use it to tell a brand kit from a website design system. |
| `profile` | Brand name, tagline, industry, copy tone, audience, values, personality, voice (`do` and `dont`), messaging, and a summary. |
| `colors` | The palette, approved text and background pairs, and where the book gives the proportions. See [Colors](#colors). |
| `typography` | Typefaces, the type hierarchy, and the fonts the PDF embeds. See [Typography](#typography). |
| `logo` | The logo concept, variants, clear space and minimum size, and misuse examples. |
| `photography` | The photographic style, and do, don't, and example images. |
| `graphics` | Graphic elements (shapes, patterns, accents, textures, illustrations), icons, and the icon style. |
| `applications` | The brand applied to media, such as social posts, ads, or merchandise. |
| `layout` | Grids, spacing rules, a measured spacing scale, and reusable templates. |
| `buttons` | Buttons the book draws, measured from the PDF, with ready-to-use CSS. See [Buttons and cards](#buttons-and-cards). |
| `cards` | Cards the book draws, with their box, text levels, and CSS. |
| `motion` | How the brand moves: what moves, how, and what it means. |
| `rules` | The book's guidelines, each with a `kind` (`do`, `dont`, or `spec`) and the `section` it belongs to. |

A section the book does not cover comes back empty: an empty list, or an object with empty fields.

### Where values come from

The kit keeps the book's word apart from what the engine worked out:

| Source | Meaning |
| - | - |
| `declared` | The book states it in its text, such as a hex code, a typeface, or a rule. |
| `measured` | Read off what the PDF draws, such as a button's radius, a type size, or a color's share in a proportion diagram. |
| `inferred` | Written by the engine from what was declared and measured, for guidance the book leaves out. |

Fields with `when_to_use` also carry `when_to_use_source` (`declared` or `inferred`). `profile.inferred` lists the profile fields the engine wrote because the book did not. `rules` contains only the book's own guidelines.

### Files from the PDF

Logos, misuse examples, photos, graphics, icons, templates, buttons, cards, and font files carry an `asset` object with a hosted `url` and a `format`:

| `format` | Meaning |
| - | - |
| `SVG` | A vector cut from the PDF. |
| `PNG` | A render of that part of the page. |
| Other | The embedded file's own type, such as `JPEG` for a photo placed in the book or `TTF` for a font. |

`asset` is `null` when the book only describes the item in words.

## Colors

Each palette color has the book's `name`, `hex`, and `group` (the book's heading, such as primary or secondary). `cmyk` and `rgb` are the values the book prints, or `null` when it prints none. They are never converted from the hex.

`proportion` says how much of the brand the color takes, as a share from 0 to 1:

| Field | Meaning |
| - | - |
| `stated` | The share the book prints in its text, such as "85% Ink". |
| `drawn` | The share the book's color page gives it, measured on the drawing: a proportion diagram, or else the swatch sizes on the page that states a share. |

Read `stated` first. `drawn` is kept even when it disagrees with `stated`, so you can see both. Either is `null` when the book does not give it.

`colors.proportion_sources` points to where the proportions come from: the `page`, the zones on it as `boxes` (`x0, y0, x1, y1` as fractions of the page), and an `asset` with the zones marked. Each source has a `kind` of `stated` or `drawn`.

`colors.pairs` lists text and background combinations as hex values, with what they are approved for (`headers`, `body`, `cta`), the WCAG 2 `contrast` ratio, and a `source`: `declared` when the book approves the pair, `measured` when the book sets text that way.

## Typography

`typography.typefaces` lists each family with its `roles`, the `weights` the book names, and a `licence` of `google_fonts` or `proprietary`.

`typography.hierarchy` lists the type levels by the book's names (headline, body copy, and so on) with `size`, `size_max` for a stated range, `line_height`, `unit` (`pt`, `px`, or empty when the book gives none), CSS `weight`, and `case`. A level is `measured` when the book gives no type scale and the engine read it off the pages.

`typography.font_files` lists the fonts the PDF embeds, to render a visual sample. An embedded font is often a subset: it only renders the glyphs in its `sample`.

## Buttons and cards

Buttons and cards are measured from the PDF's vectors, preferring a page that defines components when the book has one. Each button has a `role`, a `state`, its colors named after the palette, border, radius, padding, height, and type, plus:

| Field | Meaning |
| - | - |
| `css` | The button as CSS, converted from points (1pt = 4/3 px). Values the book states win over measured ones. |
| `declared` | The CSS the book states for buttons, as written. |

```json theme={null}
{
  "role": "primary",
  "state": "default",
  "labels": ["GET TICKETS"],
  "background": "Volt #3e6de8",
  "text_color": "Bone #f3f0e9",
  "css": {
    "background": "#3e6de8",
    "color": "#f3f0e9",
    "border": "1px solid #3e6de8",
    "border-radius": "2px",
    "padding": "15.5px 22.1px",
    "font-family": "'Whyte'",
    "font-weight": "700",
    "font-size": "12px",
    "text-transform": "uppercase",
    "letter-spacing": "0.083em"
  },
  "declared": { "border-radius": "2px" }
}
```

Cards follow the same pattern: the box (`background`, border, `radius_pt`, `padding_pt`, size), whether it holds an image (`media`), its `text` levels in reading order, and `css`.

When a book draws its components as a flat image instead of vectors, there is nothing to measure, and `buttons` or `cards` can come back empty.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.